@bnhf/prismcast 1.3.4-2026.2.19

package/dist/utils/m3u.js

@@ -0,0 +1,148 @@
+/* This module provides utilities for parsing M3U playlist files and extracting channel information. The parser handles extended M3U format with #EXTINF tags and extracts
+ * relevant attributes like tvg-name, tvg-id, and tvc-guide-stationid.
+ *
+ * Standard M3U format:
+ * #EXTM3U
+ * #EXTINF:-1 tvg-id="cnn.us" tvg-name="CNN" tvc-guide-stationid="12345",CNN Live
+ * https://example.com/cnn-stream
+ */
+// Maximum length for generated channel keys.
+const MAX_KEY_LENGTH = 50;
+/**
+ * Generates a URL-safe channel key from a display name. The key is used as the channel identifier in URLs and configuration.
+ * @param name - The display name to convert.
+ * @returns A lowercase, hyphen-separated key suitable for URLs.
+ *
+ * Examples:
+ * - "CNN Live!" → "cnn-live"
+ * - "BBC News 24/7" → "bbc-news-247"
+ * - "  Spaces  Everywhere  " → "spaces-everywhere"
+ */
+export function generateChannelKey(name) {
+    return name
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_KEY_LENGTH);
+}
+/**
+ * Extracts an attribute value from an #EXTINF line. Handles both quoted and unquoted attribute values.
+ * @param line - The #EXTINF line to parse.
+ * @param attribute - The attribute name to extract (e.g., "tvg-name").
+ * @returns The attribute value, or null if not found.
+ */
+function extractAttribute(line, attribute) {
+    // Match attribute="value" (quoted).
+    const quotedPattern = new RegExp(attribute + "=\"([^\"]*)\"", "i");
+    const quotedMatch = line.match(quotedPattern);
+    if (quotedMatch) {
+        return quotedMatch[1];
+    }
+    // Match attribute=value (unquoted, ends at space or comma).
+    const unquotedPattern = new RegExp(attribute + "=([^\\s,\"]+)", "i");
+    const unquotedMatch = line.match(unquotedPattern);
+    if (unquotedMatch) {
+        return unquotedMatch[1];
+    }
+    return null;
+}
+/**
+ * Extracts the display name from an #EXTINF line. First tries tvg-name attribute, then falls back to the comma-separated suffix.
+ * @param line - The #EXTINF line to parse.
+ * @returns The display name, or null if not found.
+ */
+function extractName(line) {
+    // First try tvg-name attribute.
+    const tvgName = extractAttribute(line, "tvg-name");
+    if (tvgName && (tvgName.trim().length > 0)) {
+        return tvgName.trim();
+    }
+    // Fall back to comma suffix (the part after the last comma in #EXTINF line). Format: #EXTINF:-1 attributes,Display Name
+    const commaIndex = line.lastIndexOf(",");
+    if (commaIndex !== -1) {
+        const suffix = line.slice(commaIndex + 1).trim();
+        if (suffix.length > 0) {
+            return suffix;
+        }
+    }
+    return null;
+}
+/**
+ * Extracts the station ID from an #EXTINF line. Prioritizes tvc-guide-stationid (Channels DVR format), falls back to tvg-id.
+ * @param line - The #EXTINF line to parse.
+ * @returns The station ID, or undefined if not found.
+ */
+function extractStationId(line) {
+    // Prioritize tvc-guide-stationid for Channels DVR compatibility.
+    const tvcStationId = extractAttribute(line, "tvc-guide-stationid");
+    if (tvcStationId && (tvcStationId.trim().length > 0)) {
+        return tvcStationId.trim();
+    }
+    // Fall back to tvg-id.
+    const tvgId = extractAttribute(line, "tvg-id");
+    if (tvgId && (tvgId.trim().length > 0)) {
+        return tvgId.trim();
+    }
+    return undefined;
+}
+/**
+ * Parses an M3U playlist and extracts channel information. Handles extended M3U format with #EXTINF tags.
+ * @param content - The M3U file content as a string.
+ * @returns Parse result containing channels and any errors encountered.
+ */
+export function parseM3U(content) {
+    const channels = [];
+    const errors = [];
+    const lines = content.split(/\r?\n/);
+    let pendingExtinf = null;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        const line = lines[i].trim();
+        // Skip empty lines and comments (except #EXTINF).
+        if ((line.length === 0) || ((line.startsWith("#")) && !line.startsWith("#EXTINF"))) {
+            continue;
+        }
+        // Parse #EXTINF line.
+        if (line.startsWith("#EXTINF:")) {
+            // If we have a pending #EXTINF without a URL, report an error.
+            if (pendingExtinf) {
+                errors.push("Line " + String(pendingExtinf.lineNumber) + ": Missing URL after #EXTINF.");
+            }
+            const name = extractName(line);
+            if (!name) {
+                errors.push("Line " + String(lineNumber) + ": Could not extract channel name from #EXTINF.");
+                pendingExtinf = null;
+                continue;
+            }
+            pendingExtinf = {
+                lineNumber,
+                name,
+                stationId: extractStationId(line)
+            };
+            continue;
+        }
+        // Parse URL line (must follow an #EXTINF).
+        if (line.startsWith("http://") || line.startsWith("https://")) {
+            if (!pendingExtinf) {
+                // URL without preceding #EXTINF - skip silently (no name available).
+                continue;
+            }
+            channels.push({
+                name: pendingExtinf.name,
+                stationId: pendingExtinf.stationId,
+                url: line
+            });
+            pendingExtinf = null;
+            continue;
+        }
+        // Unknown line format - skip silently.
+    }
+    // Check for trailing #EXTINF without URL.
+    if (pendingExtinf) {
+        errors.push("Line " + String(pendingExtinf.lineNumber) + ": Missing URL after #EXTINF.");
+    }
+    return { channels, errors };
+}
+//# sourceMappingURL=m3u.js.map

package/dist/utils/m3u.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"m3u.js","sourceRoot":"","sources":["../../src/utils/m3u.ts"],"names":[],"mappings":"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"}

package/dist/utils/morganStream.d.ts

@@ -0,0 +1,7 @@
+import type { StreamOptions } from "morgan";
+/**
+ * Creates a Morgan stream options object that routes log output based on the logging mode. When console logging is active, output goes to stdout with a timestamp
+ * prefix. When file logging is active, output goes to the file logger which adds its own timestamp.
+ * @returns StreamOptions object for Morgan configuration.
+ */
+export declare function createMorganStream(): StreamOptions;

package/dist/utils/morganStream.js

@@ -0,0 +1,33 @@
+import df from "dateformat";
+import { isConsoleLogging } from "./logger.js";
+import { writeLogEntry } from "./fileLogger.js";
+/* Morgan HTTP request logger needs a writable stream to output log entries. By default, Morgan writes to stdout. This adapter routes Morgan output to either the
+ * console or the file logger based on the current logging mode, ensuring HTTP request logs follow the same path as application logs.
+ *
+ * Timestamps are added here rather than in the Morgan format string to ensure consistency: the file logger adds timestamps via writeLogEntry(), so we add them
+ * manually for console mode to match.
+ */
+/**
+ * Creates a Morgan stream options object that routes log output based on the logging mode. When console logging is active, output goes to stdout with a timestamp
+ * prefix. When file logging is active, output goes to the file logger which adds its own timestamp.
+ * @returns StreamOptions object for Morgan configuration.
+ */
+export function createMorganStream() {
+    return {
+        write: (message) => {
+            // Remove trailing newline that Morgan adds since our loggers handle newlines.
+            const trimmedMessage = message.trim();
+            if (isConsoleLogging()) {
+                // Console logging mode - add timestamp prefix and write to stdout.
+                const timestamp = df(new Date(), "yyyy/mm/dd HH:MM:ss.l");
+                // eslint-disable-next-line no-console
+                console.log(["[", timestamp, "] ", trimmedMessage].join(""));
+            }
+            else {
+                // File logging mode - route through the file logger which adds its own timestamp.
+                writeLogEntry("info", trimmedMessage);
+            }
+        }
+    };
+}
+//# sourceMappingURL=morganStream.js.map

package/dist/utils/morganStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"morganStream.js","sourceRoot":"","sources":["../../src/utils/morganStream.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAEhC,OAAO;QAEL,KAAK,EAAE,CAAC,OAAe,EAAQ,EAAE;YAE/B,8EAA8E;YAC9E,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;YAEtC,IAAG,gBAAgB,EAAE,EAAE,CAAC;gBAEtB,mEAAmE;gBACnE,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,uBAAuB,CAAC,CAAC;gBAE1D,sCAAsC;gBACtC,OAAO,CAAC,GAAG,CAAC,CAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBAEN,kFAAkF;gBAClF,aAAa,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/platform.d.ts

@@ -0,0 +1,64 @@
+import type { Nullable } from "../types/index.js";
+export type Platform = "darwin" | "linux" | "windows";
+export type ServiceManager = "launchd" | "systemd" | "windows-scheduler";
+export declare const SERVICE_ID = "com.github.hjdhjd.prismcast";
+export declare const SERVICE_NAME = "PrismCast";
+/**
+ * Returns the current platform as a normalized string.
+ * @returns The platform: "darwin" for macOS, "linux" for Linux, "windows" for Windows.
+ */
+export declare function getPlatform(): Platform;
+/**
+ * Returns the appropriate service manager for the current platform.
+ * @returns The service manager type, or null if the platform is not supported for service installation.
+ */
+export declare function getServiceManager(): Nullable<ServiceManager>;
+/**
+ * Checks whether PrismCast is running as a managed service. This is determined by the presence of the PRISMCAST_SERVICE environment variable, which is set in the
+ * service definition file. This allows the application to adapt its restart behavior - when running as a service, exiting will trigger an automatic restart by the
+ * service manager, but when running standalone, the user must restart manually.
+ * @returns True if running as a managed service, false otherwise.
+ */
+export declare function isRunningAsService(): boolean;
+/**
+ * Returns the path where the service file should be installed for the current platform.
+ * @returns The absolute path to the service file location.
+ */
+export declare function getServiceFilePath(): string;
+/**
+ * Returns the directory containing the service file for the current platform. This directory may need to be created before writing the service file.
+ * @returns The absolute path to the service file directory.
+ */
+export declare function getServiceFileDirectory(): string;
+/**
+ * Returns the full path to the Node.js executable. This is needed for service files which require absolute paths since the service environment may not have PATH set.
+ * We prefer symlink paths (e.g., /opt/homebrew/bin/node) over resolved paths (e.g., /opt/homebrew/Cellar/node/25.4.0/bin/node) so that Homebrew and similar package
+ * managers can upgrade Node without breaking the service.
+ * @returns The absolute path to the node binary, preferring symlinks when available.
+ */
+export declare function getNodeExecutablePath(): string;
+/**
+ * Returns the full path to PrismCast's entry point (dist/index.js). This is needed for service files which require absolute paths.
+ * @returns The absolute path to the PrismCast entry point.
+ */
+export declare function getPrismCastEntryPoint(): string;
+/**
+ * Returns the working directory for PrismCast. This is the parent of the dist directory.
+ * @returns The absolute path to the PrismCast working directory.
+ */
+export declare function getPrismCastWorkingDirectory(): string;
+/**
+ * Returns the data directory path for PrismCast (~/.prismcast).
+ * @returns The absolute path to the data directory.
+ */
+export declare function getDataDirectory(): string;
+/**
+ * Returns the directory path for service stdout/stderr output. This is the same as the data directory (~/.prismcast) to keep all PrismCast files in one place.
+ * @returns The absolute path to the service logs directory.
+ */
+export declare function getLogsDirectory(): string;
+/**
+ * Checks if a service file exists at the expected location.
+ * @returns True if the service file exists.
+ */
+export declare function serviceFileExists(): boolean;

package/dist/utils/platform.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import url from "node:url";
+// Environment variable name used to detect service mode.
+const SERVICE_ENV_VAR = "PRISMCAST_SERVICE";
+// Service identifier used in service files.
+export const SERVICE_ID = "com.github.hjdhjd.prismcast";
+// Service name for display purposes.
+export const SERVICE_NAME = "PrismCast";
+/**
+ * Returns the current platform as a normalized string.
+ * @returns The platform: "darwin" for macOS, "linux" for Linux, "windows" for Windows.
+ */
+export function getPlatform() {
+    switch (process.platform) {
+        case "darwin": {
+            return "darwin";
+        }
+        case "win32": {
+            return "windows";
+        }
+        default: {
+            return "linux";
+        }
+    }
+}
+/**
+ * Returns the appropriate service manager for the current platform.
+ * @returns The service manager type, or null if the platform is not supported for service installation.
+ */
+export function getServiceManager() {
+    switch (getPlatform()) {
+        case "darwin": {
+            return "launchd";
+        }
+        case "linux": {
+            return "systemd";
+        }
+        case "windows": {
+            return "windows-scheduler";
+        }
+        default: {
+            return null;
+        }
+    }
+}
+/**
+ * Checks whether PrismCast is running as a managed service. This is determined by the presence of the PRISMCAST_SERVICE environment variable, which is set in the
+ * service definition file. This allows the application to adapt its restart behavior - when running as a service, exiting will trigger an automatic restart by the
+ * service manager, but when running standalone, the user must restart manually.
+ * @returns True if running as a managed service, false otherwise.
+ */
+export function isRunningAsService() {
+    return process.env[SERVICE_ENV_VAR] === "1";
+}
+/**
+ * Returns the path where the service file should be installed for the current platform.
+ * @returns The absolute path to the service file location.
+ */
+export function getServiceFilePath() {
+    const homeDir = os.homedir();
+    switch (getPlatform()) {
+        case "darwin": {
+            return path.join(homeDir, "Library", "LaunchAgents", SERVICE_ID + ".plist");
+        }
+        case "linux": {
+            return path.join(homeDir, ".config", "systemd", "user", "prismcast.service");
+        }
+        case "windows": {
+            // Windows Task Scheduler doesn't use a file path in the same way. We return a marker path for consistency.
+            return path.join(homeDir, ".prismcast", "service-installed.marker");
+        }
+        default: {
+            return "";
+        }
+    }
+}
+/**
+ * Returns the directory containing the service file for the current platform. This directory may need to be created before writing the service file.
+ * @returns The absolute path to the service file directory.
+ */
+export function getServiceFileDirectory() {
+    return path.dirname(getServiceFilePath());
+}
+/**
+ * Returns the full path to the Node.js executable. This is needed for service files which require absolute paths since the service environment may not have PATH set.
+ * We prefer symlink paths (e.g., /opt/homebrew/bin/node) over resolved paths (e.g., /opt/homebrew/Cellar/node/25.4.0/bin/node) so that Homebrew and similar package
+ * managers can upgrade Node without breaking the service.
+ * @returns The absolute path to the node binary, preferring symlinks when available.
+ */
+export function getNodeExecutablePath() {
+    const resolvedPath = process.execPath;
+    // Common symlink locations for Node.js on various platforms.
+    const symlinkPaths = [
+        "/opt/homebrew/bin/node",
+        "/usr/local/bin/node",
+        "/usr/bin/node",
+        "/home/linuxbrew/.linuxbrew/bin/node"
+    ];
+    // Check if any of the common symlink paths resolve to the same executable.
+    for (const symlinkPath of symlinkPaths) {
+        try {
+            const resolved = fs.realpathSync(symlinkPath);
+            if (resolved === resolvedPath) {
+                return symlinkPath;
+            }
+        }
+        catch {
+            // Symlink doesn't exist or can't be resolved; try next.
+        }
+    }
+    // No symlink found; fall back to the resolved path.
+    return resolvedPath;
+}
+/**
+ * Returns the full path to PrismCast's entry point (dist/index.js). This is needed for service files which require absolute paths.
+ * @returns The absolute path to the PrismCast entry point.
+ */
+export function getPrismCastEntryPoint() {
+    // Use import.meta.url to get the current file's path, then resolve to the entry point. This works regardless of how PrismCast was installed (npx, global, local).
+    // At runtime, this file is dist/utils/platform.js, so we go up two levels to dist/, then add index.js.
+    const currentFile = url.fileURLToPath(import.meta.url);
+    const utilsDir = path.dirname(currentFile);
+    const distDir = path.dirname(utilsDir);
+    return path.join(distDir, "index.js");
+}
+/**
+ * Returns the working directory for PrismCast. This is the parent of the dist directory.
+ * @returns The absolute path to the PrismCast working directory.
+ */
+export function getPrismCastWorkingDirectory() {
+    const entryPoint = getPrismCastEntryPoint();
+    return path.dirname(path.dirname(entryPoint));
+}
+/**
+ * Returns the data directory path for PrismCast (~/.prismcast).
+ * @returns The absolute path to the data directory.
+ */
+export function getDataDirectory() {
+    return path.join(os.homedir(), ".prismcast");
+}
+/**
+ * Returns the directory path for service stdout/stderr output. This is the same as the data directory (~/.prismcast) to keep all PrismCast files in one place.
+ * @returns The absolute path to the service logs directory.
+ */
+export function getLogsDirectory() {
+    return getDataDirectory();
+}
+/**
+ * Checks if a service file exists at the expected location.
+ * @returns True if the service file exists.
+ */
+export function serviceFileExists() {
+    return fs.existsSync(getServiceFilePath());
+}
+//# sourceMappingURL=platform.js.map

package/dist/utils/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAY3B,yDAAyD;AACzD,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAExD,qCAAqC;AACrC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,WAAW;IAEzB,QAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;QAExB,KAAK,QAAQ,CAAC,CAAC,CAAC;YAEd,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YAEb,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YAER,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAE/B,QAAO,WAAW,EAAE,EAAE,CAAC;QAErB,KAAK,QAAQ,CAAC,CAAC,CAAC;YAEd,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YAEb,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YAEf,OAAO,mBAAmB,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YAER,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAEhC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,GAAG,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAEhC,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAE7B,QAAO,WAAW,EAAE,EAAE,CAAC;QAErB,KAAK,QAAQ,CAAC,CAAC,CAAC;YAEd,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;QAC9E,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YAEb,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC;QAC/E,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YAEf,2GAA2G;YAC3G,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,0BAA0B,CAAC,CAAC;QACtE,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YAER,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IAErC,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IAEnC,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC;IAEtC,6DAA6D;IAC7D,MAAM,YAAY,GAAG;QACnB,wBAAwB;QACxB,qBAAqB;QACrB,eAAe;QACf,qCAAqC;KACtC,CAAC;IAEF,2EAA2E;IAC3E,KAAI,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QAEtC,IAAI,CAAC;YAEH,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAE9C,IAAG,QAAQ,KAAK,YAAY,EAAE,CAAC;gBAE7B,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YAEP,wDAAwD;QAC1D,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IAEpC,kKAAkK;IAClK,uGAAuG;IACvG,MAAM,WAAW,GAAG,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B;IAE1C,MAAM,UAAU,GAAG,sBAAsB,EAAE,CAAC;IAE5C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,gBAAgB,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAE/B,OAAO,EAAE,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Implements a generic retry mechanism with exponential backoff and jitter. This function attempts an operation multiple times, waiting progressively longer between
+ * attempts to avoid overwhelming failing services. The exponential backoff with jitter prevents thundering herd problems where many clients retry simultaneously.
+ * @param operation - An async function to attempt. Should throw on failure.
+ * @param maxAttempts - Maximum number of attempts before giving up.
+ * @param timeoutMs - Timeout in milliseconds for each individual attempt.
+ * @param description - Human-readable description for logging purposes.
+ * @param earlySuccessCheck - Optional async function called after timeout errors. If it returns a truthy value, that value is returned as success instead of
+ *                            retrying. Useful for cases where the operation succeeded but took too long.
+ * @param shouldAbort - Optional function called before each attempt. If it returns true, retries are aborted immediately. Useful for checking if the page was closed
+ *                      during the backoff delay.
+ * @returns The result of the operation if successful.
+ * @throws The last error encountered if all attempts fail.
+ */
+export declare function retryOperation<T>(operation: () => Promise<T>, maxAttempts: number, timeoutMs: number, description: string, earlySuccessCheck?: () => Promise<boolean>, shouldAbort?: () => boolean): Promise<T | undefined>;

package/dist/utils/retry.js

@@ -0,0 +1,82 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * retry.ts: Retry logic with exponential backoff for PrismCast.
+ */
+import { formatError, isSessionClosedError } from "./errors.js";
+import { CONFIG } from "../config/index.js";
+import { LOG } from "./logger.js";
+/* The retry system provides resilient operation execution with exponential backoff and jitter. When operations fail due to transient issues like network hiccups or
+ * slow page loads, the system automatically retries with increasing delays. The exponential backoff prevents overwhelming struggling services, while jitter prevents
+ * multiple clients from synchronizing their retry attempts.
+ */
+/**
+ * Implements a generic retry mechanism with exponential backoff and jitter. This function attempts an operation multiple times, waiting progressively longer between
+ * attempts to avoid overwhelming failing services. The exponential backoff with jitter prevents thundering herd problems where many clients retry simultaneously.
+ * @param operation - An async function to attempt. Should throw on failure.
+ * @param maxAttempts - Maximum number of attempts before giving up.
+ * @param timeoutMs - Timeout in milliseconds for each individual attempt.
+ * @param description - Human-readable description for logging purposes.
+ * @param earlySuccessCheck - Optional async function called after timeout errors. If it returns a truthy value, that value is returned as success instead of
+ *                            retrying. Useful for cases where the operation succeeded but took too long.
+ * @param shouldAbort - Optional function called before each attempt. If it returns true, retries are aborted immediately. Useful for checking if the page was closed
+ *                      during the backoff delay.
+ * @returns The result of the operation if successful.
+ * @throws The last error encountered if all attempts fail.
+ */
+export async function retryOperation(operation, maxAttempts, timeoutMs, description, earlySuccessCheck, shouldAbort) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        // Check if we should abort before starting this attempt. This catches cases where the page was closed during the backoff delay between retries.
+        if (shouldAbort?.()) {
+            throw new Error("Operation aborted: abort condition met before retry.");
+        }
+        if (attempt > 1) {
+            LOG.debug("retry", "Retrying %s (attempt %s of %s).", description, attempt, maxAttempts);
+        }
+        try {
+            // Race the operation against a timeout to prevent hanging on operations that never complete.
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(["Operation timed out after ", String(timeoutMs), "ms."].join("")));
+                }, timeoutMs);
+            });
+            // eslint-disable-next-line no-await-in-loop
+            return await Promise.race([operation(), timeoutPromise]);
+        }
+        catch (error) {
+            lastError = error;
+            // If the page or session was closed, retrying is pointless. Abort immediately without warning since we're not going to retry.
+            if (isSessionClosedError(error)) {
+                LOG.debug("retry", "Page was closed, aborting retries for %s.", description);
+                throw error;
+            }
+            // For timeout errors, check if the operation actually succeeded despite the timeout. This handles cases where the page loaded and video started playing, but
+            // some wait condition like networkidle2 never completed. We check this before logging a warning because if early success passes, there's nothing to warn about.
+            if (earlySuccessCheck && formatError(error).includes("timed out")) {
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const successResult = await earlySuccessCheck();
+                    if (successResult) {
+                        return;
+                    }
+                }
+                catch (_checkError) {
+                    // Early success check failed, continue with retry logic.
+                }
+            }
+            // If we reach here, we're going to retry (or fail after max attempts). Now log the warning since there's an actual issue to report.
+            LOG.warn("Attempt %s failed for %s: %s", attempt, description, formatError(error));
+            // Between retry attempts, wait with exponential backoff plus random jitter.
+            if (attempt < maxAttempts) {
+                const baseDelay = Math.min(1000 * Math.pow(2, attempt - 1), CONFIG.recovery.maxBackoffDelay);
+                const jitter = Math.random() * CONFIG.recovery.backoffJitter;
+                // eslint-disable-next-line no-await-in-loop
+                await new Promise((resolve) => {
+                    setTimeout(resolve, baseDelay + jitter);
+                });
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/dist/utils/streamContext.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stream context containing metadata for the current stream operation. This interface is extensible - additional fields can be added as needed without changing
+ * function signatures throughout the codebase.
+ */
+export interface StreamContext {
+    channelName?: string;
+    streamId: string;
+    url?: string;
+}
+/**
+ * Runs a function within a stream context. All async operations called within the function will have access to the stream context via getStreamContext() and
+ * getStreamId(). This should be called at stream entry points (request handlers) and at the start of timer callbacks (setInterval, setTimeout) to re-establish
+ * context.
+ * @param context - The stream context containing streamId and optional metadata.
+ * @param fn - The async function to run within the context.
+ * @returns The result of the function.
+ */
+export declare function runWithStreamContext<T>(context: StreamContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Retrieves the full stream context for the current async operation.
+ * @returns The stream context, or undefined if not running within a stream context.
+ */
+export declare function getStreamContext(): StreamContext | undefined;
+/**
+ * Convenience function to retrieve just the stream ID from the current context.
+ * @returns The stream ID, or undefined if not running within a stream context.
+ */
+export declare function getStreamId(): string | undefined;

package/dist/utils/streamContext.js

@@ -0,0 +1,33 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * streamContext.ts: AsyncLocalStorage-based stream context for automatic log correlation.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+// AsyncLocalStorage instance for stream context. This is the core mechanism that allows context to propagate through async calls.
+const streamContextStorage = new AsyncLocalStorage();
+/**
+ * Runs a function within a stream context. All async operations called within the function will have access to the stream context via getStreamContext() and
+ * getStreamId(). This should be called at stream entry points (request handlers) and at the start of timer callbacks (setInterval, setTimeout) to re-establish
+ * context.
+ * @param context - The stream context containing streamId and optional metadata.
+ * @param fn - The async function to run within the context.
+ * @returns The result of the function.
+ */
+export async function runWithStreamContext(context, fn) {
+    return streamContextStorage.run(context, fn);
+}
+/**
+ * Retrieves the full stream context for the current async operation.
+ * @returns The stream context, or undefined if not running within a stream context.
+ */
+export function getStreamContext() {
+    return streamContextStorage.getStore();
+}
+/**
+ * Convenience function to retrieve just the stream ID from the current context.
+ * @returns The stream ID, or undefined if not running within a stream context.
+ */
+export function getStreamId() {
+    return streamContextStorage.getStore()?.streamId;
+}
+//# sourceMappingURL=streamContext.js.map

package/dist/utils/streamContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamContext.js","sourceRoot":"","sources":["../../src/utils/streamContext.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA4BhD,kIAAkI;AAClI,MAAM,oBAAoB,GAAG,IAAI,iBAAiB,EAAiB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,OAAsB,EAAE,EAAoB;IAExF,OAAO,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,oBAAoB,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IAEzB,OAAO,oBAAoB,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC;AACnD,CAAC"}

package/dist/utils/version.d.ts

@@ -0,0 +1,37 @@
+import type { Nullable } from "../types/index.js";
+/**
+ * Gets the current package version from package.json.
+ * @returns The current version string (e.g., "1.0.7").
+ */
+export declare function getPackageVersion(): string;
+/**
+ * Checks for updates and caches the results.
+ * @param currentVersion - The currently running version.
+ * @param force - If true, bypasses the debounce check.
+ */
+export declare function checkForUpdates(currentVersion: string, force?: boolean): Promise<void>;
+/**
+ * Gets the cached latest version information.
+ * @param currentVersion - The currently running version.
+ * @returns Object with latest version and whether an update is available.
+ */
+export declare function getVersionInfo(currentVersion: string): {
+    latestVersion: Nullable<string>;
+    updateAvailable: boolean;
+};
+/**
+ * Gets the changelog items for a specific version as an array of strings. Uses a two-phase lookup: first checks the cache, then fetches fresh data if the
+ * version isn't found. This handles both cold cache (no data yet) and stale cache (new version not in cached data) scenarios.
+ * @param version - The version to get changelog items for.
+ * @returns Array of changelog items (bullet points), or null if unavailable.
+ */
+export declare function getChangelogItems(version: string): Promise<Nullable<string[]>>;
+/**
+ * Starts periodic update checking.
+ * @param currentVersion - The currently running version.
+ */
+export declare function startUpdateChecking(currentVersion: string): void;
+/**
+ * Stops periodic update checking.
+ */
+export declare function stopUpdateChecking(): void;