@feralfile/cli 2.0.3 → 2.1.0

package/dist/src/config.js

@@ -10,6 +10,7 @@ exports.getBrowserConfig = getBrowserConfig;
 exports.getPlaylistConfig = getPlaylistConfig;
 exports.getFeedConfig = getFeedConfig;
 exports.getFF1DeviceConfig = getFF1DeviceConfig;
+exports.getFF1RelayerConfig = getFF1RelayerConfig;
 exports.validateConfig = validateConfig;
 exports.createSampleConfig = createSampleConfig;
 const fs_1 = __importDefault(require("fs"));
@@ -188,7 +189,7 @@ function getFeedConfig() {
  * @returns {Array<Object>} returns.devices - Array of configured FF1 devices
  * @returns {string} returns.devices[].host - Device host URL
  * @returns {string} [returns.devices[].apiKey] - Optional device API key
- * @returns {string} [returns.devices[].topicID] - Optional device topic ID
+ * @returns {string} [returns.devices[].id] - Optional stable physical device ID
  * @returns {string} [returns.devices[].name] - Optional device name
  */
 function getFF1DeviceConfig() {
@@ -198,6 +199,53 @@ function getFF1DeviceConfig() {
         devices: (0, config_placeholders_1.configuredFF1Devices)(ff1Devices.devices || []),
     };
 }
+const DEFAULT_FF1_RELAYER_URL = 'https://tv-cast-coordination.autonomy-system.workers.dev';
+/**
+ * Get the FF1 relayer endpoint using repository config priority.
+ *
+ * `config.json` wins over environment variables, which win over the production
+ * default. The API key remains optional because the signed topic is the
+ * per-device credential; it exists only for deployments that retain a separate
+ * cloud-edge compatibility gate.
+ */
+function getFF1RelayerConfig() {
+    return resolveFF1RelayerConfig(getConfig());
+}
+/** Resolve and validate the effective FF1 relayer configuration. */
+function resolveFF1RelayerConfig(config) {
+    const configured = config.ff1Relayer;
+    if (configured !== undefined &&
+        (configured === null || typeof configured !== 'object' || Array.isArray(configured))) {
+        throw new Error('ff1Relayer must be an object');
+    }
+    const fields = (configured || {});
+    if (fields.baseUrl !== undefined && typeof fields.baseUrl !== 'string') {
+        throw new Error('ff1Relayer.baseUrl must be a string');
+    }
+    if (fields.apiKey !== undefined && typeof fields.apiKey !== 'string') {
+        throw new Error('ff1Relayer.apiKey must be a string');
+    }
+    const baseUrl = (fields.baseUrl ||
+        process.env.FF1_RELAYER_URL ||
+        DEFAULT_FF1_RELAYER_URL)
+        .trim()
+        .replace(/\/$/, '');
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error('ff1Relayer.baseUrl must be a valid HTTP(S) URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw new Error('ff1Relayer.baseUrl must be a valid HTTP(S) URL');
+    }
+    const apiKey = (fields.apiKey || process.env.FF1_RELAYER_API_KEY)?.trim();
+    return {
+        baseUrl,
+        apiKey: apiKey || undefined,
+    };
+}
 /**
  * Validate configuration
  *
@@ -247,6 +295,12 @@ function validateConfig() {
                 }
             }
         }
+        try {
+            resolveFF1RelayerConfig(config);
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
         return {
             valid: errors.length === 0,
             errors,

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

@@ -25,10 +25,11 @@ exports.findExistingDeviceEntry = findExistingDeviceEntry;
  * the default when prompting, rather than falling back to the raw mDNS label.
  */
 function findExistingDeviceEntry(existingDevices, newHost, discoveredName, discoveredId, discoveredAddresses) {
+    const sameDeviceId = (left, right) => Boolean(left && right && left.trim().toUpperCase() === right.trim().toUpperCase());
     // 1. mDNS device ID — stable hardware identity, checked before URL so stale
     //    host entries for other devices at the same IP do not shadow the result.
     if (discoveredId) {
-        const byId = existingDevices.find((d) => d.id === discoveredId);
+        const byId = existingDevices.find((d) => sameDeviceId(d.id, discoveredId));
         if (byId) {
             return byId;
         }
@@ -69,7 +70,7 @@ function findExistingDeviceEntry(existingDevices, newHost, discoveredName, disco
     //     the stored entry has an id; the address is the best identity signal available.
     if (discoveredAddresses && discoveredAddresses.length > 0) {
         const byDiscoveredAddress = existingDevices.find((d) => {
-            if (d.id && discoveredId && d.id !== discoveredId) {
+            if (d.id && discoveredId && !sameDeviceId(d.id, discoveredId)) {
                 return false; // different physical devices — do not conflate
             }
             try {

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

@@ -36,7 +36,17 @@ function applyPatch(existing, patch) {
     else {
         addresses = existing.addresses; // same host, no new IPs: keep stored set
     }
-    return { ...existing, ...patch, addresses };
+    const updated = { ...existing, ...patch };
+    // Rebuild the row from supported fields so an old plaintext topicID cannot
+    // survive a normal device update. Topics now belong exclusively in the OS
+    // credential vault under the stable device ID.
+    return {
+        host: updated.host,
+        name: updated.name,
+        id: updated.id,
+        apiKey: updated.apiKey,
+        addresses,
+    };
 }
 /**
  * Insert or update a device in the configured device list.
@@ -56,7 +66,11 @@ function upsertDevice(existingDevices, newDevice,
  *  heuristics below are skipped and this row is updated directly. */
 matchedIndex) {
     const devices = [...existingDevices];
-    const patch = withoutUndefined(newDevice);
+    const normalizedNewDevice = {
+        ...newDevice,
+        id: newDevice.id?.trim().toUpperCase(),
+    };
+    const patch = withoutUndefined(normalizedNewDevice);
     // Case 0: caller already resolved the match — update directly.
     if (matchedIndex !== undefined && matchedIndex >= 0 && matchedIndex < devices.length) {
         const isSameHost = devices[matchedIndex].host === newDevice.host;
@@ -64,8 +78,8 @@ matchedIndex) {
         return { devices, updated: isSameHost };
     }
     // Case 1: same mDNS device ID — update in-place even when host changed.
-    if (newDevice.id) {
-        const sameIdIndex = devices.findIndex((d) => d.id === newDevice.id);
+    if (normalizedNewDevice.id) {
+        const sameIdIndex = devices.findIndex((d) => d.id?.trim().toUpperCase() === normalizedNewDevice.id);
         if (sameIdIndex !== -1) {
             const isSameHost = devices[sameIdIndex].host === newDevice.host;
             devices[sameIdIndex] = applyPatch(devices[sameIdIndex], patch);
@@ -79,7 +93,7 @@ matchedIndex) {
         return { devices, updated: true };
     }
     // Case 3: same name, different host — replace in-place to preserve array order.
-    // Spread existing entry first so apiKey/topicID survive a host change.
+    // Spread existing entry first so non-secret device metadata survives a host change.
     const staleNameIndex = devices.findIndex((d) => d.name === newDevice.name);
     if (staleNameIndex !== -1) {
         devices[staleNameIndex] = applyPatch(devices[staleNameIndex], patch);

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

@@ -41,13 +41,27 @@ exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
 exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
 const logger = __importStar(require("../logger"));
+const config_1 = require("../config");
 const ff1_compatibility_1 = require("./ff1-compatibility");
+const ff1_relayer_1 = require("./ff1-relayer");
+const topic_store_1 = require("./topic-store");
 const SEND_RETRY_ATTEMPTS = 3;
 const SEND_RETRY_BASE_DELAY_MS = 750;
 const RATE_LIMIT_STATUS = 429;
 // Cap how long a device-supplied Retry-After can stall the CLI, so a buggy or
 // hostile device cannot pin a command for minutes/hours.
 const MAX_RETRY_DELAY_MS = 30_000;
+/** Find an FF1 `ok` flag through the nested cast response envelopes. */
+function nestedCastOk(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.ok === 'boolean') {
+        return record.ok;
+    }
+    return nestedCastOk(record.message);
+}
 /**
  * Sleep for a short duration before retrying transient network errors.
  *
@@ -162,14 +176,21 @@ function parseRetryAfterMs(headerValue) {
  *   deviceName: 'Living Room Display'
  * });
  */
-async function sendPlaylistToDevice({ playlist, deviceName, }) {
+async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
+    const dependencies = {
+        fetchFn: overrides.fetchFn ?? globalThis.fetch.bind(globalThis),
+        getTopicIdFn: overrides.getTopicIdFn ?? topic_store_1.getTopicId,
+        getRelayerConfigFn: overrides.getRelayerConfigFn ?? config_1.getFF1RelayerConfig,
+        waitFn: overrides.waitFn ?? waitForRetry,
+        noticeFn: overrides.noticeFn ?? logger.always,
+    };
     let device;
     try {
         // Validate input
         if (!playlist || typeof playlist !== 'object') {
             return {
                 success: false,
-                error: 'Invalid playlist: must provide a valid DP1 playlist object',
+                error: 'Invalid playlist: must provide a valid DP-1 playlist object',
             };
         }
         const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName);
@@ -180,7 +201,9 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
             };
         }
         device = resolved.device;
-        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist');
+        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist', {
+            fetchFn: dependencies.fetchFn,
+        });
         if (!compatibility.compatible) {
             return {
                 success: false,
@@ -189,12 +212,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
             };
         }
         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}`);
-        }
+        const apiUrl = `${device.host}/api/cast`;
         // Wrap playlist in required structure
         const requestBody = {
             command: 'displayPlaylist',
@@ -221,7 +239,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
         let lastBodyIssue = null;
         for (let attempt = 1; attempt <= SEND_RETRY_ATTEMPTS; attempt += 1) {
             try {
-                response = await fetch(apiUrl, {
+                response = await dependencies.fetchFn(apiUrl, {
                     method: 'POST',
                     headers,
                     body: JSON.stringify(requestBody),
@@ -234,7 +252,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     const retryDelay = Math.min(retryAfterMs ?? SEND_RETRY_BASE_DELAY_MS * attempt, MAX_RETRY_DELAY_MS);
                     logger.warn(`Device rate-limited the command (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
                     response = null;
-                    await waitForRetry(retryDelay);
+                    await dependencies.waitFn(retryDelay);
                     continue;
                 }
                 // Non-2xx (other than 429 handled above): surface via the post-loop
@@ -263,7 +281,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     const retryDelay = SEND_RETRY_BASE_DELAY_MS * attempt;
                     logger.warn(`${lastBodyIssue} (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
                     response = null;
-                    await waitForRetry(retryDelay);
+                    await dependencies.waitFn(retryDelay);
                     continue;
                 }
                 // Out of attempts; let the post-loop handler report the body issue.
@@ -277,17 +295,22 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                 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);
+                await dependencies.waitFn(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: ff-cli setup',
-            };
+            return fallbackToRelayer({
+                playlist,
+                device,
+                dependencies,
+                lanFailure: {
+                    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: ff-cli setup',
+                },
+            });
         }
         // Check response status
         if (!response.ok) {
@@ -321,6 +344,13 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     'wait a few seconds and try again.',
             };
         }
+        if (nestedCastOk(responseData) === false) {
+            return {
+                success: false,
+                error: `Device "${device.name || device.host}" rejected the display command`,
+                details: JSON.stringify(responseData),
+            };
+        }
         logger.info('Successfully sent playlist to FF1 device');
         logger.debug(`Device response: ${JSON.stringify(responseData)}`);
         return {
@@ -329,6 +359,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
             deviceName: device.name || device.host,
             response: responseData,
             message: 'Playlist successfully sent to FF1 device',
+            transport: 'lan',
         };
     }
     catch (error) {
@@ -336,12 +367,17 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
         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: ff-cli setup',
-            };
+            return fallbackToRelayer({
+                playlist,
+                device,
+                dependencies,
+                lanFailure: {
+                    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: ff-cli setup',
+                },
+            });
         }
         return {
             success: false,
@@ -349,3 +385,69 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
         };
     }
 }
+/**
+ * Fall back to the relayer only after LAN reachability is exhausted.
+ *
+ * Topic lookup is keyed by the stable physical device ID and happens only at
+ * the fallback boundary, keeping the credential out of config and normal LAN
+ * requests. Application/HTTP errors do not enter this path.
+ */
+async function fallbackToRelayer(input) {
+    if (!input.device.id) {
+        return {
+            ...input.lanFailure,
+            details: `${input.lanFailure.details} Pair the relayer with: ff-cli device pair ${input.device.name ?? '<device>'}`,
+        };
+    }
+    let topicId;
+    try {
+        topicId = input.dependencies.getTopicIdFn(input.device.id);
+    }
+    catch (error) {
+        return {
+            ...input.lanFailure,
+            details: `${input.lanFailure.details} Secure topic storage is unavailable: ${error.message}`,
+        };
+    }
+    if (!topicId) {
+        return {
+            ...input.lanFailure,
+            details: `${input.lanFailure.details} Pair this device for relayer fallback with: ff-cli device pair ${input.device.name ?? input.device.id}`,
+        };
+    }
+    input.dependencies.noticeFn(`Notice: LAN device is unreachable; falling back to the FF1 relayer for ${input.device.name ?? input.device.id}.`);
+    let relayer;
+    try {
+        relayer = input.dependencies.getRelayerConfigFn();
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: 'Invalid FF1 relayer configuration',
+            details: error.message,
+            transport: 'relayer',
+        };
+    }
+    const result = await (0, ff1_relayer_1.sendPlaylistViaRelayer)({
+        ...relayer,
+        topicId,
+        playlist: input.playlist,
+        fetchFn: input.dependencies.fetchFn,
+    });
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error,
+            details: result.details,
+            transport: 'relayer',
+        };
+    }
+    return {
+        success: true,
+        device: relayer.baseUrl,
+        deviceName: input.device.name ?? input.device.id,
+        response: result.response,
+        message: 'Playlist successfully sent through the FF1 relayer',
+        transport: 'relayer',
+    };
+}

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

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendPlaylistViaRelayer = sendPlaylistViaRelayer;
+function nestedOk(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.ok === 'boolean') {
+        return record.ok;
+    }
+    return nestedOk(record.message);
+}
+/**
+ * sendPlaylistViaRelayer sends a display command through the mobile-compatible
+ * FF1 relayer contract.
+ *
+ * The result preserves the relayer's HTTP failure status before interpreting
+ * any response body. Successful responses must contain JSON when non-empty;
+ * non-2xx responses may use plain text or HTML without obscuring the original
+ * gateway failure.
+ *
+ * @param input - Relayer endpoint, optional compatibility key, paired topic,
+ * playlist, and optional fetch implementation.
+ * @returns A structured result for handled request failures, HTTP statuses,
+ * and JSON parsing errors.
+ */
+async function sendPlaylistViaRelayer(input) {
+    const fetchFn = input.fetchFn ?? globalThis.fetch.bind(globalThis);
+    let url;
+    try {
+        url = new URL('/api/cast', input.baseUrl);
+    }
+    catch {
+        return {
+            success: false,
+            error: 'Invalid FF1 relayer configuration',
+            details: 'ff1Relayer.baseUrl must be a valid HTTP(S) URL',
+        };
+    }
+    url.searchParams.set('topicID', input.topicId);
+    const headers = { 'Content-Type': 'application/json' };
+    if (input.apiKey) {
+        headers['API-KEY'] = input.apiKey;
+    }
+    let response;
+    try {
+        response = await fetchFn(url, {
+            // The relayer accepts GET or POST with the same body. Node's standards-
+            // compliant fetch rejects GET bodies, so CLI uses POST while preserving
+            // the mobile request shape and topic query parameter.
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                command: 'displayPlaylist',
+                request: {
+                    dp1_call: input.playlist,
+                    intent: { action: 'now_display' },
+                },
+            }),
+        });
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: 'Could not reach the FF1 relayer',
+            details: error.message,
+        };
+    }
+    const bodyText = (await response.text()).trim();
+    // HTTP status is authoritative for gateway failures. Parse only successful
+    // responses so an HTML/plain-text 401 cannot hide the actionable missing-key
+    // diagnosis behind a secondary JSON parsing error.
+    if (!response.ok) {
+        const needsCompatibilityKey = response.status === 401 && !input.apiKey;
+        return {
+            success: false,
+            error: `FF1 relayer returned HTTP ${response.status}`,
+            details: needsCompatibilityKey
+                ? 'This relayer deployment still requires its optional FF1_RELAYER_API_KEY compatibility gate.'
+                : bodyText || response.statusText,
+        };
+    }
+    let data = {};
+    if (bodyText) {
+        try {
+            data = JSON.parse(bodyText);
+        }
+        catch {
+            return {
+                success: false,
+                error: `FF1 relayer returned non-JSON HTTP ${response.status}`,
+                details: bodyText.slice(0, 200),
+            };
+        }
+    }
+    if (nestedOk(data) === false) {
+        return {
+            success: false,
+            error: 'FF1 rejected the relayer display command',
+            details: bodyText,
+        };
+    }
+    return { success: true, response: data };
+}

package/dist/src/utilities/functions.js

@@ -259,7 +259,7 @@ async function verifyAddresses(params) {
  * @returns {Array<Object>} returns.devices - Array of device configurations
  * @returns {string} returns.devices[].name - Device name
  * @returns {string} returns.devices[].host - Device host URL
- * @returns {string} [returns.devices[].topicID] - Optional topic ID
+ * @returns {string} [returns.devices[].id] - Optional physical device ID
  * @returns {string} [returns.error] - Error message if no devices configured
  * @example
  * const result = await getConfiguredDevices();
@@ -291,7 +291,7 @@ async function getConfiguredDevices() {
     const devices = deviceConfig.devices.map((d) => ({
         name: d.name || d.host,
         host: d.host,
-        topicID: d.topicID,
+        id: d.id,
     }));
     return {
         success: true,

package/dist/src/utilities/handoff-client.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopicHandoffReceiver = void 0;
+const handoff_crypto_1 = require("./handoff-crypto");
+const DEFAULT_HANDOFF_URL = 'https://handoff.feralfile.com';
+function brokerBaseUrl(value) {
+    return (value || process.env.FF1_HANDOFF_URL || DEFAULT_HANDOFF_URL).replace(/\/$/, '');
+}
+async function responseJson(response, operation) {
+    if (!response.ok) {
+        throw new Error(`${operation} failed with HTTP ${response.status}`);
+    }
+    return response.json();
+}
+function parseCreated(value) {
+    const record = value;
+    if (!record ||
+        typeof record.channelId !== 'string' ||
+        !record.channelId.startsWith('ch_') ||
+        typeof record.minterToken !== 'string' ||
+        typeof record.shortCode !== 'string' ||
+        !/^\d{6}$/.test(record.shortCode) ||
+        typeof record.expiresAt !== 'string') {
+        throw new Error('handoff channel response is invalid');
+    }
+    return record;
+}
+function parsePoll(value, channelId) {
+    const record = value;
+    if (record?.channelId !== channelId || !Array.isArray(record.messages)) {
+        throw new Error('handoff poll response is invalid');
+    }
+    return record;
+}
+function parseTopicPayload(value, channelId, expectedDeviceId) {
+    const payload = value;
+    if (payload?.v !== 1 ||
+        payload.type !== 'ff1_topic_handoff' ||
+        payload.channelId !== channelId ||
+        typeof payload.deviceId !== 'string' ||
+        payload.deviceId.trim().toUpperCase() !== expectedDeviceId.trim().toUpperCase() ||
+        typeof payload.topicId !== 'string' ||
+        payload.topicId.trim().length === 0 ||
+        typeof payload.sentAt !== 'string' ||
+        Number.isNaN(Date.parse(payload.sentAt))) {
+        throw new Error('received topic handoff does not match the selected FF1 device');
+    }
+    return payload;
+}
+/** One short-lived CLI-side channel waiting for a mobile topic transfer. */
+class TopicHandoffReceiver {
+    baseUrl;
+    channelId;
+    shortCode;
+    verificationCode;
+    expiresAt;
+    minterToken;
+    privateKey;
+    fetchFn;
+    constructor(baseUrl, channelId, shortCode, verificationCode, expiresAt, minterToken, privateKey, fetchFn) {
+        this.baseUrl = baseUrl;
+        this.channelId = channelId;
+        this.shortCode = shortCode;
+        this.verificationCode = verificationCode;
+        this.expiresAt = expiresAt;
+        this.minterToken = minterToken;
+        this.privateKey = privateKey;
+        this.fetchFn = fetchFn;
+    }
+    /** Ask the handoff broker for a one-time six-digit pairing channel. */
+    static async create(options = {}) {
+        const fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+        const baseUrl = brokerBaseUrl(options.baseUrl);
+        const keyPair = await (0, handoff_crypto_1.generateHandoffKeyPair)();
+        const publicKey = await (0, handoff_crypto_1.exportHandoffPublicJwk)(keyPair.publicKey);
+        const response = await fetchFn(new URL('/v1/channels', baseUrl), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                algorithm: handoff_crypto_1.HANDOFF_ALGORITHM,
+                minterPublicKeyJwk: publicKey,
+                idleTtlSeconds: 300,
+                shortCodeRequested: true,
+            }),
+        });
+        const created = parseCreated(await responseJson(response, 'handoff channel creation'));
+        const verificationCode = (0, handoff_crypto_1.handoffVerificationCode)({
+            channelId: created.channelId,
+            minterPublicKeyJwk: publicKey,
+        });
+        return new TopicHandoffReceiver(baseUrl, created.channelId, created.shortCode, verificationCode, created.expiresAt, created.minterToken, keyPair.privateKey, fetchFn);
+    }
+    /** Poll until mobile sends a valid encrypted topic for the selected device. */
+    async receiveTopic(options) {
+        const deadline = Date.now() + (options.maxWaitMs ?? 300_000);
+        let afterSeq = 0;
+        while (Date.now() <= deadline) {
+            const url = new URL(`/v1/channels/${encodeURIComponent(this.channelId)}/messages`, this.baseUrl);
+            url.searchParams.set('afterSeq', String(afterSeq));
+            const response = await this.fetchFn(url, {
+                headers: { Authorization: `Bearer ${this.minterToken}` },
+            });
+            const poll = parsePoll(await responseJson(response, 'handoff poll'), this.channelId);
+            for (const message of poll.messages) {
+                afterSeq = Math.max(afterSeq, message.seq);
+                if (message.sender !== 'browser' ||
+                    message.recipient !== 'minter' ||
+                    !message.senderPublicKeyJwk) {
+                    continue;
+                }
+                const plaintext = await (0, handoff_crypto_1.decryptHandoffMessage)({
+                    privateKey: this.privateKey,
+                    peerPublicKeyJwk: message.senderPublicKeyJwk,
+                    channelId: this.channelId,
+                    seq: message.seq,
+                    message,
+                });
+                return parseTopicPayload(plaintext, this.channelId, options.expectedDeviceId);
+            }
+            await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1000));
+        }
+        throw new Error('Timed out waiting for the mobile app topic transfer');
+    }
+    /** Close the broker channel and invalidate its participant credentials. */
+    async close() {
+        const response = await this.fetchFn(new URL(`/v1/channels/${encodeURIComponent(this.channelId)}`, this.baseUrl), {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${this.minterToken}` },
+        });
+        if (!response.ok && response.status !== 404 && response.status !== 410) {
+            throw new Error(`handoff channel close failed with HTTP ${response.status}`);
+        }
+    }
+}
+exports.TopicHandoffReceiver = TopicHandoffReceiver;