@bnhf/prismcast 1.3.4-2026.2.19

package/dist/utils/format.js

@@ -0,0 +1,46 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * format.ts: Formatting utilities for PrismCast.
+ */
+/**
+ * Formats a duration in milliseconds as a human-readable string. The format varies based on duration length:
+ * - Less than 60 seconds: "17s"
+ * - Less than 1 hour: "6m 39s"
+ * - 1 hour or more: "1h 23m"
+ * @param ms - Duration in milliseconds.
+ * @returns Formatted duration string.
+ */
+export function formatDuration(ms) {
+    const totalSeconds = Math.round(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return [String(hours), "h ", String(minutes), "m"].join("");
+    }
+    if (minutes > 0) {
+        return [String(minutes), "m ", String(seconds), "s"].join("");
+    }
+    return [String(seconds), "s"].join("");
+}
+/**
+ * Extracts a concise domain from a URL by keeping only the last two portions of the hostname (e.g., "watch.foodnetwork.com" becomes "foodnetwork.com",
+ * "www.hulu.com" becomes "hulu.com"). Used as a standard domain key for DOMAIN_CONFIG lookups and as a display fallback when no provider name is configured.
+ * @param url - The URL to extract the domain from.
+ * @returns The concise domain, or the original URL if parsing fails.
+ */
+export function extractDomain(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        const parts = hostname.split(".");
+        // Keep only the last two parts (e.g., "foodnetwork.com"). For single-part hostnames (e.g., "localhost"), return as-is.
+        if (parts.length > 2) {
+            return parts.slice(-2).join(".");
+        }
+        return hostname;
+    }
+    catch {
+        return url;
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IAEvC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,YAAY,GAAG,EAAE,CAAC;IAElC,IAAG,KAAK,GAAG,CAAC,EAAE,CAAC;QAEb,OAAO,CAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,IAAG,OAAO,GAAG,CAAC,EAAE,CAAC;QAEf,OAAO,CAAE,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,CAAE,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IAEvC,IAAI,CAAC;QAEH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAElC,uHAAuH;QACvH,IAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAEpB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QAEP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/utils/html.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Escapes HTML special characters in a string to prevent XSS when displaying user-provided or dynamic content in HTML.
+ * @param text - The text to escape.
+ * @returns The escaped text safe for HTML display.
+ */
+export declare function escapeHtml(text: string): string;

package/dist/utils/html.js

@@ -0,0 +1,24 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * html.ts: HTML utilities for PrismCast.
+ */
+/* This utility provides HTML escaping for safely embedding dynamic content in HTML responses.
+ */
+/**
+ * Escapes HTML special characters in a string to prevent XSS when displaying user-provided or dynamic content in HTML.
+ * @param text - The text to escape.
+ * @returns The escaped text safe for HTML display.
+ */
+export function escapeHtml(text) {
+    const replacements = {
+        "\"": """,
+        "&": "&",
+        "'": "'",
+        "<": "&lt;",
+        ">": "&gt;"
+    };
+    return text.replace(/[&<>"']/g, (char) => {
+        return replacements[char];
+    });
+}
+//# sourceMappingURL=html.js.map

package/dist/utils/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/utils/html.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;GACG;AAEH;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IAErC,MAAM,YAAY,GAA2B;QAE3C,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,OAAO;QACZ,GAAG,EAAE,OAAO;QACZ,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,MAAM;KACZ,CAAC;IAEF,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;QAEvC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./debugFilter.js";
+export * from "./delay.js";
+export * from "./errors.js";
+export * from "./evaluate.js";
+export * from "./ffmpeg.js";
+export * from "./format.js";
+export * from "./html.js";
+export * from "./logEmitter.js";
+export * from "./logger.js";
+export * from "./m3u.js";
+export * from "./morganStream.js";
+export * from "./platform.js";
+export * from "./retry.js";
+export * from "./streamContext.js";
+export * from "./version.js";

package/dist/utils/index.js

@@ -0,0 +1,20 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * index.ts: Utility module exports for PrismCast.
+ */
+export * from "./debugFilter.js";
+export * from "./delay.js";
+export * from "./errors.js";
+export * from "./evaluate.js";
+export * from "./ffmpeg.js";
+export * from "./format.js";
+export * from "./html.js";
+export * from "./logEmitter.js";
+export * from "./logger.js";
+export * from "./m3u.js";
+export * from "./morganStream.js";
+export * from "./platform.js";
+export * from "./retry.js";
+export * from "./streamContext.js";
+export * from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}

package/dist/utils/logEmitter.d.ts

@@ -0,0 +1,17 @@
+export interface LogEntry {
+    categoryTag?: string;
+    level: "debug" | "error" | "info" | "warn";
+    message: string;
+    timestamp: string;
+}
+/**
+ * Emits a log entry to all subscribed SSE clients.
+ * @param entry - The log entry to broadcast.
+ */
+export declare function emitLogEntry(entry: LogEntry): void;
+/**
+ * Subscribes a callback to receive log entries. Returns an unsubscribe function.
+ * @param callback - Function to call when a log entry is emitted.
+ * @returns A function to unsubscribe the callback.
+ */
+export declare function subscribeToLogs(callback: (entry: LogEntry) => void): () => void;

package/dist/utils/logEmitter.js

@@ -0,0 +1,30 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logEmitter.ts: Event emitter for real-time log streaming via SSE.
+ */
+import { EventEmitter } from "events";
+/* A singleton EventEmitter that broadcasts log entries to all subscribed SSE clients. When a log entry is written via LOG.info/warn/error, the entry is emitted here
+ * for real-time streaming to connected browsers.
+ */
+const logEmitter = new EventEmitter();
+// Increase the default listener limit to support many concurrent SSE connections. Each browser tab viewing the Logs tab will have its own listener.
+logEmitter.setMaxListeners(100);
+/**
+ * Emits a log entry to all subscribed SSE clients.
+ * @param entry - The log entry to broadcast.
+ */
+export function emitLogEntry(entry) {
+    logEmitter.emit("log", entry);
+}
+/**
+ * Subscribes a callback to receive log entries. Returns an unsubscribe function.
+ * @param callback - Function to call when a log entry is emitted.
+ * @returns A function to unsubscribe the callback.
+ */
+export function subscribeToLogs(callback) {
+    logEmitter.on("log", callback);
+    return () => {
+        logEmitter.off("log", callback);
+    };
+}
+//# sourceMappingURL=logEmitter.js.map

package/dist/utils/logEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logEmitter.js","sourceRoot":"","sources":["../../src/utils/logEmitter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AActC;;GAEG;AAEH,MAAM,UAAU,GAAG,IAAI,YAAY,EAAE,CAAC;AAEtC,oJAAoJ;AACpJ,UAAU,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAe;IAE1C,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAmC;IAEjE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE/B,OAAO,GAAS,EAAE;QAEhB,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Sets the logging mode. When true, logs go to console with colors. When false, logs go to the file logger.
+ * @param enabled - True to enable console logging, false for file logging.
+ */
+export declare function setConsoleLogging(enabled: boolean): void;
+/**
+ * Returns whether console logging is currently enabled.
+ * @returns True if using console logging, false if using file logging.
+ */
+export declare function isConsoleLogging(): boolean;
+/**
+ * Enables or disables debug logging. When called with true, initializes the debug filter with wildcard (*) to enable all categories.
+ * @param enabled - True to enable all debug logging, false to disable.
+ */
+export declare function setDebugLogging(enabled: boolean): void;
+/**
+ * Returns whether any debug logging is currently enabled.
+ * @returns True if any debug categories are enabled, false otherwise.
+ */
+export declare function isDebugLogging(): boolean;
+/**
+ * Bound logger interface returned by LOG.withStreamId(). Provides the same logging methods but with a fixed stream ID.
+ */
+interface BoundLogger {
+    debug: (category: string, message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+}
+export declare const LOG: {
+    /**
+     * Logs a debug message in cyan, filtered by category. Debug messages are only output when the specified category is enabled via the PRISMCAST_DEBUG environment
+     * variable or the --debug CLI flag (which enables all categories). Use this for verbose diagnostic information that would clutter normal logs.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param category - The debug category (e.g., "tuning:hulu", "recovery:tab", "streaming:segmenter").
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    debug: (category: string, message: string, ...args: unknown[]) => void;
+    /**
+     * Logs an error message in red. Use this for critical failures that prevent normal operation, such as browser crashes, navigation failures after all retries, or
+     * stream initialization errors. The red color provides immediate visual indication of serious problems requiring attention.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs an informational message in the default terminal color. Use this for normal operational messages like startup notifications, successful operations, and
+     * status updates.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    info: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs a warning message in yellow. Use this for non-critical issues that do not prevent operation but indicate potential problems, such as timeouts that were
+     * recovered from, missing optional features, or degraded functionality.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Creates a bound logger with a fixed stream ID. Use this when logging about a stream from outside its async context, such as when iterating over multiple streams
+     * in a disconnect handler or cleanup routine.
+     *
+     * Example:
+     *   const streamLog = LOG.withStreamId(streamId);
+     *   streamLog.warn("Terminating stream due to browser disconnect.");
+     *   streamLog.info("Cleanup complete.");
+     *
+     * @param streamId - The stream ID to include in all log messages.
+     * @returns A logger object with debug, error, warn, and info methods that include the specified stream ID.
+     */
+    withStreamId: (streamId: string) => BoundLogger;
+};
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,219 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logger.ts: Logging utilities with color-coded output for PrismCast.
+ */
+import { initDebugFilter, isAnyDebugEnabled, isCategoryEnabled } from "./debugFilter.js";
+import { emitLogEntry } from "./logEmitter.js";
+import { format } from "util";
+import { getStreamId } from "./streamContext.js";
+import { writeLogEntry } from "./fileLogger.js";
+/* Terminal color codes for log output formatting. Warnings appear in yellow and errors in red, making it easy to spot issues when scanning log output. The reset
+ * code restores the default color after each colored message to prevent color bleeding into subsequent output.
+ */
+const ANSI_COLORS = {
+    cyan: "\x1b[36m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m",
+    yellow: "\x1b[33m"
+};
+/* The logger can operate in two modes: console mode (output to stdout/stderr with colors) or file mode (output to ~/.prismcast/prismcast.log). By default, file mode
+ * is used. Console mode is enabled via the --console CLI flag for Docker deployments or interactive debugging.
+ */
+// Flag indicating whether to use console logging instead of file logging.
+let useConsoleLogging = false;
+/**
+ * Sets the logging mode. When true, logs go to console with colors. When false, logs go to the file logger.
+ * @param enabled - True to enable console logging, false for file logging.
+ */
+export function setConsoleLogging(enabled) {
+    useConsoleLogging = enabled;
+}
+/**
+ * Returns whether console logging is currently enabled.
+ * @returns True if using console logging, false if using file logging.
+ */
+export function isConsoleLogging() {
+    return useConsoleLogging;
+}
+/* Debug logging is controlled by the category-based filter system in debugFilter.ts. The --debug CLI flag enables all categories (equivalent to
+ * PRISMCAST_DEBUG=*), while the PRISMCAST_DEBUG environment variable allows fine-grained category selection.
+ */
+/**
+ * Enables or disables debug logging. When called with true, initializes the debug filter with wildcard (*) to enable all categories.
+ * @param enabled - True to enable all debug logging, false to disable.
+ */
+export function setDebugLogging(enabled) {
+    initDebugFilter(enabled ? "*" : "");
+}
+/**
+ * Returns whether any debug logging is currently enabled.
+ * @returns True if any debug categories are enabled, false otherwise.
+ */
+export function isDebugLogging() {
+    return isAnyDebugEnabled();
+}
+/* The LOG object provides a centralized logging interface with color-coded output and printf-style format strings. All methods accept a format string followed by
+ * optional arguments, using Node's util.format() for interpolation. Supported format specifiers include %s (string), %d (number), %j (JSON), and %o (object).
+ *
+ * Stream context is automatically detected via AsyncLocalStorage. When running within a stream context (established by runWithStreamContext()), log messages are
+ * automatically prefixed with the stream ID for correlation across concurrent streaming sessions.
+ *
+ * For logging outside a stream context (e.g., iterating over streams in a disconnect handler), use LOG.withStreamId() to create a bound logger.
+ */
+/**
+ * Formats the current time as a timestamp string matching the log file format.
+ * @returns A timestamp string in the format "YYYY/MM/DD HH:MM:ss.lll".
+ */
+function formatTimestamp() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    const hours = String(now.getHours()).padStart(2, "0");
+    const minutes = String(now.getMinutes()).padStart(2, "0");
+    const seconds = String(now.getSeconds()).padStart(2, "0");
+    const ms = String(now.getMilliseconds()).padStart(3, "0");
+    return [year, "/", month, "/", day, " ", hours, ":", minutes, ":", seconds, ".", ms].join("");
+}
+/**
+ * Emits a log entry to SSE subscribers for real-time streaming.
+ * @param level - The log level.
+ * @param message - The formatted message.
+ * @param categoryTag - Optional debug category tag for category-filtered debug messages.
+ */
+function emitToSubscribers(level, message, categoryTag) {
+    const entry = {
+        level,
+        message,
+        timestamp: formatTimestamp()
+    };
+    if (categoryTag) {
+        entry.categoryTag = categoryTag;
+    }
+    emitLogEntry(entry);
+}
+/**
+ * Core logging implementation shared by all log levels. Handles stream ID prefixing, SSE emission, and output routing.
+ * @param level - The log level (error, warn, info, debug).
+ * @param color - ANSI color code for console output (empty string for no color).
+ * @param message - The format string.
+ * @param args - Format arguments.
+ * @param explicitStreamId - Optional explicit stream ID (used by withStreamId helper).
+ * @param categoryTag - Optional debug category tag for category-filtered debug messages.
+ */
+function logWithLevel(level, color, message, args, explicitStreamId, categoryTag) {
+    const streamId = explicitStreamId ?? getStreamId();
+    const formatted = args.length > 0 ? format(message, ...args) : message;
+    const logMessage = streamId ? ["[", streamId, "] ", formatted].join("") : formatted;
+    // Emit to SSE subscribers for real-time streaming.
+    emitToSubscribers(level, logMessage, categoryTag);
+    if (useConsoleLogging) {
+        /* eslint-disable no-console */
+        let consoleMethod;
+        switch (level) {
+            case "error": {
+                consoleMethod = console.error;
+                break;
+            }
+            case "warn": {
+                consoleMethod = console.warn;
+                break;
+            }
+            default: {
+                consoleMethod = console.log;
+                break;
+            }
+        }
+        /* eslint-enable no-console */
+        if (streamId && color) {
+            consoleMethod("%s[%s] %s%s", color, streamId, formatted, ANSI_COLORS.reset);
+        }
+        else if (streamId) {
+            consoleMethod("[%s] %s", streamId, formatted);
+        }
+        else if (color) {
+            consoleMethod("%s%s%s", color, formatted, ANSI_COLORS.reset);
+        }
+        else {
+            consoleMethod(formatted);
+        }
+    }
+    else {
+        writeLogEntry(level, logMessage, color || undefined, categoryTag);
+    }
+}
+export const LOG = {
+    /**
+     * Logs a debug message in cyan, filtered by category. Debug messages are only output when the specified category is enabled via the PRISMCAST_DEBUG environment
+     * variable or the --debug CLI flag (which enables all categories). Use this for verbose diagnostic information that would clutter normal logs.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param category - The debug category (e.g., "tuning:hulu", "recovery:tab", "streaming:segmenter").
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    debug: function (category, message, ...args) {
+        if (!isAnyDebugEnabled() || !isCategoryEnabled(category)) {
+            return;
+        }
+        logWithLevel("debug", ANSI_COLORS.cyan, message, args, undefined, category);
+    },
+    /**
+     * Logs an error message in red. Use this for critical failures that prevent normal operation, such as browser crashes, navigation failures after all retries, or
+     * stream initialization errors. The red color provides immediate visual indication of serious problems requiring attention.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    error: function (message, ...args) {
+        logWithLevel("error", ANSI_COLORS.red, message, args);
+    },
+    /**
+     * Logs an informational message in the default terminal color. Use this for normal operational messages like startup notifications, successful operations, and
+     * status updates.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    info: function (message, ...args) {
+        logWithLevel("info", "", message, args);
+    },
+    /**
+     * Logs a warning message in yellow. Use this for non-critical issues that do not prevent operation but indicate potential problems, such as timeouts that were
+     * recovered from, missing optional features, or degraded functionality.
+     *
+     * Stream ID is automatically included if running within a stream context (established by runWithStreamContext()).
+     * @param message - The format string (supports %s, %d, %j, %o).
+     * @param args - Values to interpolate into the format string.
+     */
+    warn: function (message, ...args) {
+        logWithLevel("warn", ANSI_COLORS.yellow, message, args);
+    },
+    /**
+     * Creates a bound logger with a fixed stream ID. Use this when logging about a stream from outside its async context, such as when iterating over multiple streams
+     * in a disconnect handler or cleanup routine.
+     *
+     * Example:
+     *   const streamLog = LOG.withStreamId(streamId);
+     *   streamLog.warn("Terminating stream due to browser disconnect.");
+     *   streamLog.info("Cleanup complete.");
+     *
+     * @param streamId - The stream ID to include in all log messages.
+     * @returns A logger object with debug, error, warn, and info methods that include the specified stream ID.
+     */
+    withStreamId: function (streamId) {
+        return {
+            debug: (category, message, ...args) => {
+                if (isAnyDebugEnabled() && isCategoryEnabled(category)) {
+                    logWithLevel("debug", ANSI_COLORS.cyan, message, args, streamId, category);
+                }
+            },
+            error: (message, ...args) => { logWithLevel("error", ANSI_COLORS.red, message, args, streamId); },
+            info: (message, ...args) => { logWithLevel("info", "", message, args, streamId); },
+            warn: (message, ...args) => { logWithLevel("warn", ANSI_COLORS.yellow, message, args, streamId); }
+        };
+    }
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/m3u.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents a channel parsed from an M3U playlist.
+ */
+export interface M3UChannel {
+    name: string;
+    stationId?: string;
+    url: string;
+}
+/**
+ * Result of parsing an M3U playlist.
+ */
+export interface M3UParseResult {
+    channels: M3UChannel[];
+    errors: string[];
+}
+/**
+ * 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 declare function generateChannelKey(name: string): string;
+/**
+ * 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 declare function parseM3U(content: string): M3UParseResult;