@bharper/atv-js 0.2.3

package/src/companion/keyboard.ts

@@ -0,0 +1,155 @@
+/**
+ * Keyboard/text input via Companion protocol.
+ * Port of pyatv/protocols/companion/api.py text input handling +
+ * pyatv/protocols/companion/__init__.py CompanionKeyboard.
+ */
+
+import { CompanionProtocol } from './protocol';
+import { createRtiClearTextPayload, createRtiInputTextPayload, readArchiveProperties } from '../bplist';
+
+export enum KeyboardFocusState {
+  Unknown = 'unknown',
+  Focused = 'focused',
+  Unfocused = 'unfocused',
+}
+
+export interface KeyboardState {
+  focusState: KeyboardFocusState;
+}
+
+/**
+ * Start a text input session. Returns the response containing _tiD if keyboard is focused.
+ */
+async function textInputStart(protocol: CompanionProtocol): Promise<Record<string, unknown>> {
+  return protocol.sendCommand('_tiStart', {});
+}
+
+/**
+ * Stop a text input session.
+ */
+async function textInputStop(protocol: CompanionProtocol): Promise<Record<string, unknown>> {
+  return protocol.sendCommand('_tiStop', {});
+}
+
+/**
+ * Execute a text input command: optionally clear existing text, then append new text.
+ * Returns the current text after the operation, or null if keyboard not focused.
+ */
+export async function textInputCommand(
+  protocol: CompanionProtocol,
+  text: string,
+  clearPreviousInput: boolean,
+): Promise<string | null> {
+  // Restart session to get latest state
+  await textInputStop(protocol);
+  const response = await textInputStart(protocol);
+
+  const content = (response._c || {}) as Record<string, unknown>;
+  const tiData = content._tiD;
+
+  if (!tiData || !Buffer.isBuffer(tiData)) {
+    return null; // Keyboard not focused
+  }
+
+  // Extract session UUID and current text from NSKeyedArchiver data
+  const [sessionUuid, currentTextRaw] = readArchiveProperties(
+    tiData,
+    ['sessionUUID'],
+    ['documentState', 'docSt', 'contextBeforeInput'],
+  );
+
+  if (!sessionUuid || !Buffer.isBuffer(sessionUuid)) {
+    return null;
+  }
+
+  let currentText: string = typeof currentTextRaw === 'string' ? currentTextRaw : '';
+
+  // Clear text if requested
+  if (clearPreviousInput) {
+    protocol.sendEvent('_tiC', {
+      _tiV: 1,
+      _tiD: createRtiClearTextPayload(sessionUuid),
+    });
+    currentText = '';
+  }
+
+  // Append new text
+  if (text) {
+    protocol.sendEvent('_tiC', {
+      _tiV: 1,
+      _tiD: createRtiInputTextPayload(sessionUuid, text),
+    });
+    currentText += text;
+  }
+
+  return currentText;
+}
+
+/**
+ * Get the current text from a focused keyboard.
+ */
+export async function getText(protocol: CompanionProtocol): Promise<string | null> {
+  return textInputCommand(protocol, '', false);
+}
+
+/**
+ * Set (replace) the text in a focused keyboard.
+ */
+export async function setText(protocol: CompanionProtocol, text: string): Promise<void> {
+  await textInputCommand(protocol, text, true);
+}
+
+/**
+ * Check if keyboard is currently focused by starting a text input session.
+ */
+export async function getKeyboardFocus(protocol: CompanionProtocol): Promise<boolean> {
+  await textInputStop(protocol);
+  const response = await textInputStart(protocol);
+  const content = (response._c || {}) as Record<string, unknown>;
+  return '_tiD' in content && content._tiD !== null && content._tiD !== undefined;
+}
+
+/**
+ * Register keyboard focus state listeners on a protocol instance.
+ * Uses polling since _tiStarted/_tiStopped events aren't reliably pushed.
+ * Calls the callback whenever focus state changes.
+ * Returns a function to stop the polling.
+ */
+export function watchKeyboardFocus(
+  protocol: CompanionProtocol,
+  callback: (state: KeyboardFocusState) => void,
+  pollIntervalMs = 1000,
+): () => void {
+  let lastState: KeyboardFocusState = KeyboardFocusState.Unknown;
+  let running = true;
+
+  const poll = async () => {
+    if (!running) return;
+
+    try {
+      const focused = await getKeyboardFocus(protocol);
+      const newState = focused ? KeyboardFocusState.Focused : KeyboardFocusState.Unfocused;
+
+      if (newState !== lastState) {
+        lastState = newState;
+        callback(newState);
+      }
+    } catch {
+      // Connection may be closed, stop polling
+      running = false;
+      return;
+    }
+
+    if (running) {
+      setTimeout(poll, pollIntervalMs);
+    }
+  };
+
+  // Start polling
+  poll();
+
+  // Return stop function
+  return () => {
+    running = false;
+  };
+}

package/src/companion/pairing_keepalive.ts

@@ -0,0 +1,75 @@
+import { CompanionConnection } from './connection';
+
+const COMPANION_AGENT_IDLE_MS = 2 * 60 * 1000;
+
+type Entry = {
+  connection: CompanionConnection;
+  lastUsed: number;
+  timer: NodeJS.Timeout;
+};
+
+const connectionCache = new Map<string, Entry>();
+
+function connectionKey(host: string, port: number): string {
+  return `${host}:${port}`;
+}
+
+function scheduleCleanup(key: string, entry: Entry): void {
+  if (entry.timer) clearTimeout(entry.timer);
+  entry.lastUsed = Date.now();
+  entry.timer = setTimeout(() => {
+    if (Date.now() - entry.lastUsed >= COMPANION_AGENT_IDLE_MS) {
+      entry.connection.close();
+      connectionCache.delete(key);
+    }
+  }, COMPANION_AGENT_IDLE_MS);
+  if (typeof entry.timer.unref === 'function') entry.timer.unref();
+}
+
+export function getCompanionPairingConnection(host: string, port: number): CompanionConnection {
+  const key = connectionKey(host, port);
+  const existing = connectionCache.get(key);
+  if (existing) {
+    if (existing.connection.isConnected) {
+      scheduleCleanup(key, existing);
+      return existing.connection;
+    }
+    existing.connection.close();
+    connectionCache.delete(key);
+  }
+
+  const connection = new CompanionConnection(host, port);
+  const entry: Entry = {
+    connection,
+    lastUsed: Date.now(),
+    timer: setTimeout(() => {
+      connection.close();
+      connectionCache.delete(key);
+    }, COMPANION_AGENT_IDLE_MS),
+  };
+  if (typeof entry.timer.unref === 'function') entry.timer.unref();
+  connectionCache.set(key, entry);
+  return connection;
+}
+
+export function releaseCompanionPairingConnection(connection: CompanionConnection): void {
+  const key = connectionKey(connection.getHost(), connection.getPort());
+  const existing = connectionCache.get(key);
+  if (existing) {
+    scheduleCleanup(key, existing);
+  } else {
+    const entry: Entry = {
+      connection,
+      lastUsed: Date.now(),
+      timer: setTimeout(() => {
+        connection.close();
+        connectionCache.delete(key);
+      }, COMPANION_AGENT_IDLE_MS),
+    };
+    if (typeof entry.timer.unref === 'function') entry.timer.unref();
+    connectionCache.set(key, entry);
+  }
+
+  // Detach listener to avoid delivering stale events.
+  connection.setListener({ frameReceived: () => {}, connectionLost: () => {} });
+}

package/src/companion/protocol.ts

@@ -0,0 +1,253 @@
+/**
+ * Companion protocol message dispatch layer.
+ * Port of pyatv/protocols/companion/protocol.py.
+ *
+ * Messages are OPACK-encoded with structure:
+ *   { _i: identifier, _t: messageType, _c: content, _x: transactionId }
+ */
+
+import { EventEmitter } from 'events';
+import { CompanionConnection, FrameType, FrameListener } from './connection';
+import * as opack from '../opack';
+import { SRPAuthHandler } from '../pairing/srp';
+import { HapCredentials, parseCredentials } from '../pairing/credentials';
+import { CompanionPairVerifyProcedure, SRP_SALT, SRP_OUTPUT_INFO, SRP_INPUT_INFO } from './auth';
+
+export enum MessageType {
+  Event = 1,
+  Request = 2,
+  Response = 3,
+}
+
+const DEFAULT_TIMEOUT = 5000;
+
+interface PendingRequest {
+  resolve: (data: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface CompanionEventListener {
+  (data: Record<string, unknown>): void;
+}
+
+export class CompanionProtocol implements FrameListener {
+  connection: CompanionConnection;
+  private xid = Math.floor(Math.random() * 0x10000); // Random starting xid like pyatv
+  private pendingRequests = new Map<number, PendingRequest>();
+  private pendingAuth = new Map<number, PendingRequest>(); // keyed by frame type
+  private eventListeners = new Map<string, CompanionEventListener[]>();
+  private events = new EventEmitter();
+  private srp: SRPAuthHandler;
+  private credentialString: string | null;
+  private _onConnectionLost?: (error?: Error) => void;
+
+  constructor(connection: CompanionConnection, credentialString: string | null) {
+    this.connection = connection;
+    this.srp = new SRPAuthHandler();
+    this.credentialString = credentialString;
+  }
+
+  set onConnectionLost(handler: (error?: Error) => void) {
+    this._onConnectionLost = handler;
+  }
+
+  // ---- FrameListener interface ----
+
+  frameReceived(frameType: FrameType, payload: Buffer): void {
+    // Auth frames (PS_*, PV_*)
+    if (frameType >= FrameType.PS_Start && frameType <= FrameType.PV_Next) {
+      this.handleAuthFrame(frameType, payload);
+      return;
+    }
+
+    // OPACK frames
+    if (frameType === FrameType.E_OPACK || frameType === FrameType.U_OPACK || frameType === FrameType.P_OPACK) {
+      if (payload.length === 0) return;
+      const { value } = opack.unpack(payload);
+      this.handleOpack(frameType, value as Record<string, unknown>);
+    }
+  }
+
+  connectionLost(error?: Error): void {
+    // Reject all pending requests
+    for (const [, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Connection lost'));
+    }
+    this.pendingRequests.clear();
+
+    for (const [, pending] of this.pendingAuth) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Connection lost'));
+    }
+    this.pendingAuth.clear();
+
+    if (this._onConnectionLost) this._onConnectionLost(error);
+  }
+
+  // ---- Auth frame handling ----
+
+  private handleAuthFrame(frameType: FrameType, payload: Buffer): void {
+    if (payload.length === 0) return;
+    const { value } = opack.unpack(payload);
+    const data = value as Record<string, unknown>;
+
+    // Auth responses come as the next frame type after the request
+    // PV_Start(5) → response comes as PV_Next(6), PS_Start(3) → PS_Next(4)
+    const pending = this.pendingAuth.get(frameType);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingAuth.delete(frameType);
+      pending.resolve(data);
+    }
+  }
+
+  /**
+   * Exchange an auth frame and wait for the response.
+   */
+  async exchangeAuth(
+    frameType: FrameType,
+    data: Record<string, unknown>,
+    timeout = DEFAULT_TIMEOUT,
+  ): Promise<Record<string, unknown>> {
+    // Response frame type: for PS_Start(3)→PS_Next(4), PV_Start(5)→PV_Next(6)
+    // For PS_Next(4)→PS_Next(4), PV_Next(6)→PV_Next(6)
+    let responseType: FrameType;
+    if (frameType === FrameType.PS_Start) {
+      responseType = FrameType.PS_Next;
+    } else if (frameType === FrameType.PV_Start) {
+      responseType = FrameType.PV_Next;
+    } else {
+      responseType = frameType; // PS_Next → PS_Next, PV_Next → PV_Next
+    }
+
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingAuth.delete(responseType);
+        reject(new Error(`Auth exchange timeout for frame type ${frameType}`));
+      }, timeout);
+
+      this.pendingAuth.set(responseType, { resolve, reject, timer });
+      this.connection.send(frameType, opack.pack(data));
+    });
+  }
+
+  // ---- OPACK message handling ----
+
+  private handleOpack(frameType: FrameType, data: Record<string, unknown>): void {
+    const messageType = data._t as number;
+
+    if (messageType === MessageType.Event) {
+      const eventName = data._i as string;
+      const content = (data._c || {}) as Record<string, unknown>;
+      const listeners = this.eventListeners.get(eventName);
+      if (listeners) {
+        for (const listener of listeners) {
+          try { listener(content); } catch {}
+        }
+      }
+      this.events.emit(eventName, content);
+    } else if (messageType === MessageType.Response) {
+      const xid = data._x as number;
+      const pending = this.pendingRequests.get(xid);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(xid);
+        pending.resolve(data);
+      }
+    }
+  }
+
+  /**
+   * Send an OPACK request and wait for the response.
+   */
+  async exchangeOpack(
+    data: Record<string, unknown>,
+    frameType: FrameType = FrameType.E_OPACK,
+    timeout = DEFAULT_TIMEOUT,
+  ): Promise<Record<string, unknown>> {
+    const xid = this.xid++;
+    data._x = xid;
+
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(xid);
+        reject(new Error(`OPACK exchange timeout for xid ${xid}`));
+      }, timeout);
+
+      this.pendingRequests.set(xid, { resolve, reject, timer });
+      this.connection.send(frameType, opack.pack(data));
+    });
+  }
+
+  /**
+   * Send an OPACK event (no response expected).
+   */
+  sendEvent(identifier: string, content: Record<string, unknown>): void {
+    const data: Record<string, unknown> = {
+      _i: identifier,
+      _t: MessageType.Event,
+      _c: content,
+      _x: this.xid++,
+    };
+    this.connection.send(FrameType.E_OPACK, opack.pack(data));
+  }
+
+  /**
+   * Send an OPACK request with standard message structure.
+   */
+  async sendCommand(
+    identifier: string,
+    content: Record<string, unknown> = {},
+    timeout = DEFAULT_TIMEOUT,
+  ): Promise<Record<string, unknown>> {
+    const data: Record<string, unknown> = {
+      _i: identifier,
+      _t: MessageType.Request,
+      _c: content,
+    };
+    return this.exchangeOpack(data, FrameType.E_OPACK, timeout);
+  }
+
+  /**
+   * Register a listener for a specific event name.
+   */
+  listenTo(eventName: string, listener: CompanionEventListener): void {
+    const existing = this.eventListeners.get(eventName) || [];
+    existing.push(listener);
+    this.eventListeners.set(eventName, existing);
+  }
+
+  /**
+   * Subscribe to device events.
+   */
+  async subscribeEvent(eventName: string): Promise<void> {
+    this.sendEvent('_interest', { _regEvents: [eventName] });
+  }
+
+  // ---- Connection lifecycle ----
+
+  /**
+   * Start the protocol: connect, verify credentials if available, enable encryption.
+   */
+  async start(): Promise<void> {
+    await this.connection.connect();
+
+    if (this.credentialString) {
+      const credentials = parseCredentials(this.credentialString);
+      await this.setupEncryption(credentials);
+    }
+  }
+
+  private async setupEncryption(credentials: HapCredentials): Promise<void> {
+    const verifier = new CompanionPairVerifyProcedure(this, this.srp, credentials);
+    await verifier.verifyCredentials();
+    const [outputKey, inputKey] = verifier.encryptionKeys();
+    this.connection.enableEncryption(outputKey, inputKey);
+  }
+
+  close(): void {
+    this.connection.close();
+  }
+}

package/src/companion/remote.ts

@@ -0,0 +1,151 @@
+/**
+ * Remote control via Companion protocol HID and media control commands.
+ * Port of pyatv/protocols/companion/api.py + __init__.py remote control.
+ */
+
+import { CompanionProtocol } from './protocol';
+
+/** HID command values matching pyatv's HidCommand enum. */
+export enum HidCommand {
+  Up = 1,
+  Down = 2,
+  Left = 3,
+  Right = 4,
+  Menu = 5,
+  Select = 6,
+  Home = 7,
+  VolumeUp = 8,
+  VolumeDown = 9,
+  Siri = 10,
+  Screensaver = 11,
+  Sleep = 12,
+  Wake = 13,
+  PlayPause = 14,
+  ChannelIncrement = 15,
+  ChannelDecrement = 16,
+  Guide = 17,
+  PageUp = 18,
+  PageDown = 19,
+}
+
+/** Media control command values matching pyatv's MediaControlCommand enum. */
+export enum MediaControlCommand {
+  Play = 1,
+  Pause = 2,
+  NextTrack = 3,
+  PreviousTrack = 4,
+  GetVolume = 5,
+  SetVolume = 6,
+  SkipBy = 7,
+}
+
+/** Named remote keys. */
+export enum RemoteKey {
+  Up = 'up',
+  Down = 'down',
+  Left = 'left',
+  Right = 'right',
+  Select = 'select',
+  Menu = 'menu',
+  TopMenu = 'top_menu',
+  Home = 'home',
+  HomeHold = 'home_hold',
+  PlayPause = 'play_pause',
+  Next = 'next',
+  Previous = 'previous',
+  SkipForward = 'skip_forward',
+  SkipBackward = 'skip_backward',
+  VolumeUp = 'volume_up',
+  VolumeDown = 'volume_down',
+  Guide = 'guide',
+}
+
+const KEY_TO_HID: Record<string, HidCommand> = {
+  [RemoteKey.Up]: HidCommand.Up,
+  [RemoteKey.Down]: HidCommand.Down,
+  [RemoteKey.Left]: HidCommand.Left,
+  [RemoteKey.Right]: HidCommand.Right,
+  [RemoteKey.Select]: HidCommand.Select,
+  [RemoteKey.Menu]: HidCommand.Menu,
+  [RemoteKey.TopMenu]: HidCommand.Menu,
+  [RemoteKey.Home]: HidCommand.Home,
+  [RemoteKey.HomeHold]: HidCommand.Home,
+  [RemoteKey.PlayPause]: HidCommand.PlayPause,
+  [RemoteKey.VolumeUp]: HidCommand.VolumeUp,
+  [RemoteKey.VolumeDown]: HidCommand.VolumeDown,
+  [RemoteKey.Guide]: HidCommand.Guide,
+};
+
+/** Keys that are media control commands rather than HID. */
+const KEY_TO_MEDIA: Record<string, MediaControlCommand> = {
+  [RemoteKey.Next]: MediaControlCommand.NextTrack,
+  [RemoteKey.Previous]: MediaControlCommand.PreviousTrack,
+};
+
+/** Keys that require a long press (hold down, delay, release). */
+const LONG_PRESS_KEYS = new Set<string>([RemoteKey.HomeHold]);
+
+const LONG_PRESS_DELAY_MS = 1000;
+
+/**
+ * Send a media control command.
+ */
+export async function sendMediaControl(
+  protocol: CompanionProtocol,
+  command: MediaControlCommand,
+  args?: Record<string, unknown>,
+): Promise<void> {
+  await protocol.sendCommand('_mcc', { _mcc: command, ...(args || {}) });
+}
+
+/**
+ * Send a remote control key press. Handles HID keys, media control keys,
+ * and long-press keys automatically.
+ */
+export async function sendKeyPress(protocol: CompanionProtocol, key: RemoteKey | string): Promise<void> {
+  // Media control keys
+  const mediaCommand = KEY_TO_MEDIA[key];
+  if (mediaCommand !== undefined) {
+    await sendMediaControl(protocol, mediaCommand);
+    return;
+  }
+
+  const hidCommand = KEY_TO_HID[key];
+  if (hidCommand === undefined) {
+    throw new Error(`Unknown remote key: ${key}`);
+  }
+
+  if (LONG_PRESS_KEYS.has(key)) {
+    // Long press: hold down, wait, release
+    await protocol.sendCommand('_hidC', { _hBtS: 1, _hidC: hidCommand });
+    await new Promise((r) => setTimeout(r, LONG_PRESS_DELAY_MS));
+    await protocol.sendCommand('_hidC', { _hBtS: 2, _hidC: hidCommand });
+    return;
+  }
+
+  // Normal press: down + up
+  await protocol.sendCommand('_hidC', { _hBtS: 1, _hidC: hidCommand });
+  await protocol.sendCommand('_hidC', { _hBtS: 2, _hidC: hidCommand });
+}
+
+/**
+ * Send a HID button down event only (for long press behavior).
+ */
+export async function sendKeyDown(protocol: CompanionProtocol, key: RemoteKey | string): Promise<void> {
+  const hidCommand = KEY_TO_HID[key];
+  if (hidCommand === undefined) {
+    throw new Error(`Unknown remote key: ${key}`);
+  }
+  await protocol.sendCommand('_hidC', { _hBtS: 1, _hidC: hidCommand });
+}
+
+/**
+ * Send a HID button up event only (to release a held button).
+ */
+export async function sendKeyUp(protocol: CompanionProtocol, key: RemoteKey | string): Promise<void> {
+  const hidCommand = KEY_TO_HID[key];
+  if (hidCommand === undefined) {
+    throw new Error(`Unknown remote key: ${key}`);
+  }
+  await protocol.sendCommand('_hidC', { _hBtS: 2, _hidC: hidCommand });
+}