@feralfile/cli 1.1.1

package/dist/src/utilities/ff1-compatibility.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * FF1 device compatibility helpers for command preflight checks.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfiguredDevice = resolveConfiguredDevice;
+exports.assertFF1CommandCompatibility = assertFF1CommandCompatibility;
+const config_1 = require("../config");
+const logger = __importStar(require("../logger"));
+const FF1_COMMAND_POLICIES = {
+    displayPlaylist: {
+        minimumVersion: '1.0.0',
+    },
+    sshAccess: {
+        minimumVersion: '1.0.9',
+    },
+};
+/**
+ * Load and validate the configured FF1 device selected by name.
+ *
+ * @param {string} [deviceName] - Optional device name, exact match required
+ * @param {Object} [options] - Optional dependency overrides
+ * @param {Function} [options.getFF1DeviceConfigFn] - Optional config loader override
+ * @returns {FF1DeviceSelectionResult} Selected device or reason for failure
+ * @throws {Error} Never throws; malformed configuration is returned as an error result
+ * @example
+ * const result = resolveConfiguredDevice('Living Room');
+ */
+function resolveConfiguredDevice(deviceName, options = {}) {
+    const getFF1DeviceConfigFn = options.getFF1DeviceConfigFn || config_1.getFF1DeviceConfig;
+    const deviceConfig = getFF1DeviceConfigFn();
+    if (!deviceConfig.devices || deviceConfig.devices.length === 0) {
+        return {
+            success: false,
+            error: 'No FF1 devices configured. Add devices to config.json under "ff1Devices"',
+        };
+    }
+    let device = deviceConfig.devices[0];
+    if (deviceName) {
+        device = deviceConfig.devices.find((item) => item.name === deviceName);
+        if (!device) {
+            const availableNames = deviceConfig.devices
+                .map((item) => item.name)
+                .filter(Boolean)
+                .join(', ');
+            return {
+                success: false,
+                error: `Device "${deviceName}" not found. Available devices: ${availableNames || 'none with names'}`,
+            };
+        }
+        logger.info(`Found device by name: ${deviceName}`);
+    }
+    else {
+        logger.info('Using first configured device');
+    }
+    if (!device.host) {
+        return {
+            success: false,
+            error: 'Invalid device configuration: must include host',
+        };
+    }
+    return {
+        success: true,
+        device,
+    };
+}
+/**
+ * Ensure the target device supports the requested FF1 command.
+ *
+ * @param {Object} device - FF1 device configuration
+ * @param {FF1Command} command - Command to execute
+ * @param {Object} [options] - Optional dependency overrides
+ * @param {Function} [options.fetchFn] - Optional fetch implementation
+ * @returns {Promise<FF1CompatibilityResult>} Compatibility result
+ * @throws {Error} Never throws; network and parsing failures produce a compatible result
+ * @example
+ * const result = await assertFF1CommandCompatibility(device, 'displayPlaylist');
+ */
+async function assertFF1CommandCompatibility(device, command, options = {}) {
+    const fetchFn = options.fetchFn || globalThis.fetch.bind(globalThis);
+    const policy = getCommandPolicy(command);
+    const versionResult = await detectFF1VersionSafely(device.host, buildVersionHeaders(device), fetchFn);
+    return resolveCompatibility(device, command, policy, versionResult);
+}
+/**
+ * Return command compatibility requirements.
+ *
+ * @param {FF1Command} command - Command to check
+ * @returns {FF1CommandPolicy} Policy metadata
+ * @example
+ * getCommandPolicy('sshAccess'); // { minimumVersion: '1.0.0' }
+ */
+function getCommandPolicy(command) {
+    return FF1_COMMAND_POLICIES[command];
+}
+/**
+ * Detect FF1 version and recover compatibility when detection fails.
+ *
+ * @param {string} host - Device host URL
+ * @param {Object} headers - Request headers
+ * @param {Function} fetchFn - Fetch implementation
+ * @returns {Promise<FF1VersionProbe | null>} Detected version metadata
+ */
+async function detectFF1VersionSafely(host, headers, fetchFn) {
+    try {
+        return await detectFF1Version(host, headers, fetchFn);
+    }
+    catch (error) {
+        logger.debug('FF1 version detection failed; continuing with command', error.message);
+        return null;
+    }
+}
+/**
+ * Resolve final compatibility decision from detected version and policy.
+ *
+ * @param {FF1Device} device - Target device
+ * @param {FF1Command} command - Command requested
+ * @param {FF1CommandPolicy} policy - Version policy
+ * @param {FF1VersionProbe | null} versionResult - Detected version probe
+ * @returns {FF1CompatibilityResult} Compatibility decision
+ */
+function resolveCompatibility(device, command, policy, versionResult) {
+    if (!versionResult) {
+        logger.warn(`Could not verify FF1 OS version for ${device.name || device.host}`);
+        return { compatible: true };
+    }
+    const normalizedVersion = normalizeVersion(versionResult.version);
+    if (!normalizedVersion) {
+        return {
+            compatible: true,
+            version: versionResult.version,
+        };
+    }
+    if (compareVersions(normalizedVersion, policy.minimumVersion) < 0) {
+        return {
+            compatible: false,
+            version: normalizedVersion,
+            error: `Unsupported FF1 OS ${normalizedVersion} for ${command}. FF1 OS must be ${policy.minimumVersion} or newer.`,
+        };
+    }
+    return {
+        compatible: true,
+        version: normalizedVersion,
+    };
+}
+/**
+ * Detect FF1 OS version via POST /api/cast with getDeviceStatus command.
+ *
+ * Reads `message.installedVersion` from the device status response.
+ *
+ * @param {string} host - Device host URL
+ * @param {Record<string, string>} headers - Request headers (e.g. API-KEY)
+ * @param {FetchFunction} fetchFn - Fetch implementation
+ * @returns {Promise<FF1VersionProbe | null>} Version probe or null if unavailable
+ * @example
+ * const probe = await detectFF1Version('http://ff1.local', {}, fetch);
+ */
+async function detectFF1Version(host, headers, fetchFn) {
+    try {
+        const response = await fetchFn(`${host}/api/cast`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ command: 'getDeviceStatus', request: {} }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        const version = data?.message?.installedVersion;
+        if (!version) {
+            return null;
+        }
+        return { version };
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * Build headers shared by cast requests.
+ *
+ * @param {FF1Device} device - Target device
+ * @returns {Record<string, string>} Headers map
+ * @example
+ * const headers = buildVersionHeaders(device);
+ */
+function buildVersionHeaders(device) {
+    const headers = {};
+    if (device.apiKey) {
+        headers['API-KEY'] = device.apiKey;
+    }
+    return headers;
+}
+/**
+ * Parse and normalize a version string to x.y.z format.
+ *
+ * @param {string} version - Raw version string
+ * @returns {string | null} Normalized semver-like version
+ * @example
+ * normalizeVersion('v1.2') // '1.2.0'
+ */
+function normalizeVersion(version) {
+    const raw = version.trim();
+    const match = raw.match(/(?:v)?(\d+)\.(\d+)(?:\.(\d+))?/);
+    if (!match) {
+        return null;
+    }
+    const major = match[1];
+    const minor = match[2];
+    const patch = match[3] || '0';
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * Compare two semantic versions in x.y.z format.
+ *
+ * @param {string} left - First version
+ * @param {string} right - Second version
+ * @returns {number} 1 if left > right, -1 if left < right, 0 if equal
+ * @example
+ * compareVersions('1.2.1', '1.2.0'); // 1
+ */
+function compareVersions(left, right) {
+    const leftParts = left.split('.').map((value) => Number.parseInt(value, 10));
+    const rightParts = right.split('.').map((value) => Number.parseInt(value, 10));
+    for (let i = 0; i < 3; i++) {
+        const leftPart = leftParts[i] || 0;
+        const rightPart = rightParts[i] || 0;
+        if (leftPart > rightPart) {
+            return 1;
+        }
+        if (leftPart < rightPart) {
+            return -1;
+        }
+    }
+    return 0;
+}

package/dist/src/utilities/ff1-device.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * FF1 Device Communication Module
+ * Handles sending DP1 playlists to FF1 devices via the Relayer API
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
+exports.sendPlaylistToDevice = sendPlaylistToDevice;
+const logger = __importStar(require("../logger"));
+const ff1_compatibility_1 = require("./ff1-compatibility");
+const SEND_RETRY_ATTEMPTS = 3;
+const SEND_RETRY_BASE_DELAY_MS = 750;
+/**
+ * Sleep for a short duration before retrying transient network errors.
+ *
+ * @param {number} delayMs - Milliseconds to wait
+ * @returns {Promise<void>} Promise that resolves after the delay
+ */
+function waitForRetry(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}
+/**
+ * isTransientDeviceNetworkError returns true when a send failure is likely temporary.
+ *
+ * This classifier intentionally targets resolver and route-level failures that are
+ * common on local mDNS/Wi-Fi environments. Permanent command errors should surface
+ * immediately without retry loops.
+ *
+ * @param {unknown} error - Error thrown by fetch
+ * @returns {boolean} True when retrying is likely to recover
+ */
+function isTransientDeviceNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const networkCodes = new Set([
+        'EHOSTUNREACH',
+        'ENETUNREACH',
+        'ENOTFOUND',
+        'EAI_AGAIN',
+        'ETIMEDOUT',
+        'ECONNREFUSED',
+        'ECONNRESET',
+    ]);
+    const message = error.message || '';
+    const messageLooksTransient = message.includes('fetch failed') ||
+        message.includes('getaddrinfo') ||
+        message.includes('EHOSTUNREACH') ||
+        message.includes('ENOTFOUND') ||
+        message.includes('ETIMEDOUT') ||
+        message.includes('network timeout') ||
+        message.includes('No route to host');
+    if (messageLooksTransient) {
+        return true;
+    }
+    const causeCode = error.cause &&
+        typeof error.cause === 'object' &&
+        'code' in error.cause &&
+        typeof error.cause.code === 'string'
+        ? error.cause.code
+        : undefined;
+    return Boolean(causeCode && networkCodes.has(causeCode));
+}
+/**
+ * Send a DP1 playlist to an FF1 device using the cast API
+ *
+ * This function sends the entire DP1 JSON payload to a configured FF1 device.
+ * If a device name is provided, it searches for a device with that exact name.
+ * If no device name is provided, it uses the first configured device.
+ * The API-KEY header is only included if the device has an apiKey configured.
+ *
+ * @param {Object} params - Function parameters
+ * @param {Object} params.playlist - Complete DP1 v1.0.0 playlist object to send
+ * @param {string} [params.deviceName] - Name of the device to send to (exact match required)
+ * @returns {Promise<Object>} Result object
+ * @returns {boolean} returns.success - Whether the cast was successful
+ * @returns {string} [returns.device] - Device host that received the playlist
+ * @returns {string} [returns.deviceName] - Name of the device used
+ * @returns {Object} [returns.response] - Response from the device
+ * @returns {string} [returns.error] - Error message if failed
+ * @throws {Error} When device configuration is invalid or missing
+ * @example
+ * // Send to first device
+ * const result = await sendPlaylistToDevice({
+ *   playlist: { version: '1.0.0', title: 'My Collection', items: [...] }
+ * });
+ *
+ * @example
+ * // Send to specific device by name
+ * const result = await sendPlaylistToDevice({
+ *   playlist: { version: '1.0.0', title: 'My Collection', items: [...] },
+ *   deviceName: 'Living Room Display'
+ * });
+ */
+async function sendPlaylistToDevice({ playlist, deviceName, }) {
+    let device;
+    try {
+        // Validate input
+        if (!playlist || typeof playlist !== 'object') {
+            return {
+                success: false,
+                error: 'Invalid playlist: must provide a valid DP1 playlist object',
+            };
+        }
+        const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName);
+        if (!resolved.success || !resolved.device) {
+            return {
+                success: false,
+                error: resolved.error || 'FF1 device is not configured correctly',
+            };
+        }
+        device = resolved.device;
+        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist');
+        if (!compatibility.compatible) {
+            return {
+                success: false,
+                error: compatibility.error || 'FF1 OS does not support playlist casting',
+                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
+            };
+        }
+        logger.info(`Sending playlist to FF1 device: ${device.host}`);
+        // Construct API URL with optional topicID
+        let apiUrl = `${device.host}/api/cast`;
+        if (device.topicID && device.topicID.trim() !== '') {
+            apiUrl += `?topicID=${encodeURIComponent(device.topicID)}`;
+            logger.debug(`Using topicID: ${device.topicID}`);
+        }
+        // Wrap playlist in required structure
+        const requestBody = {
+            command: 'displayPlaylist',
+            request: {
+                dp1_call: playlist,
+                intent: { action: 'now_display' },
+            },
+        };
+        // Prepare headers
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Add API-KEY header only if apiKey is provided
+        if (device.apiKey) {
+            headers['API-KEY'] = device.apiKey;
+        }
+        // Make the API request with bounded retries for transient local network errors.
+        let response = null;
+        for (let attempt = 1; attempt <= SEND_RETRY_ATTEMPTS; attempt += 1) {
+            try {
+                response = await fetch(apiUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(requestBody),
+                });
+                break;
+            }
+            catch (error) {
+                const shouldRetry = attempt < SEND_RETRY_ATTEMPTS && isTransientDeviceNetworkError(error);
+                if (!shouldRetry) {
+                    throw error;
+                }
+                const retryDelay = SEND_RETRY_BASE_DELAY_MS * attempt;
+                logger.warn(`Transient network error while sending playlist (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}): ${error.message}`);
+                logger.debug(`Retrying playlist send in ${retryDelay}ms`);
+                await waitForRetry(retryDelay);
+            }
+        }
+        if (!response) {
+            const deviceLabel = device.name || device.host;
+            return {
+                success: false,
+                error: `Could not reach device "${deviceLabel}" at ${device.host}`,
+                details: 'Check that the device is powered on and reachable on your network. ' +
+                    'If the device IP changed (e.g. after a factory reset), run: ff1 setup',
+            };
+        }
+        // Check response status
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.error(`Failed to cast to device: ${response.status} ${response.statusText}`);
+            logger.debug(`Error details: ${errorText}`);
+            return {
+                success: false,
+                error: `Device returned error ${response.status}: ${response.statusText}`,
+                details: errorText,
+            };
+        }
+        // Parse response
+        const responseData = (await response.json());
+        logger.info('Successfully sent playlist to FF1 device');
+        logger.debug(`Device response: ${JSON.stringify(responseData)}`);
+        return {
+            success: true,
+            device: device.host,
+            deviceName: device.name || device.host,
+            response: responseData,
+            message: 'Playlist successfully sent to FF1 device',
+        };
+    }
+    catch (error) {
+        const errorMessage = error.message;
+        logger.error(`Error sending playlist to device: ${errorMessage}`);
+        if (device && isTransientDeviceNetworkError(error)) {
+            const deviceLabel = device.name || device.host;
+            return {
+                success: false,
+                error: `Could not reach device "${deviceLabel}" at ${device.host}`,
+                details: 'Check that the device is powered on and reachable on your network. ' +
+                    'If the device IP changed (e.g. after a factory reset), run: ff1 setup',
+            };
+        }
+        return {
+            success: false,
+            error: errorMessage,
+        };
+    }
+}