@corewire/companion-link 0.0.0 → 1.0.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,705 @@
+import { EventEmitter } from "node:events";
+import { ConnectionClosedError } from "@corewire/core";
+import { CloseReason, Context, DeviceIdentity, EncryptionAwareConnection } from "@corewire/core/transport";
+import { AccessoryCredentials, PairSetup } from "@corewire/core/pairing";
+import { DiscoverOptions, DiscoveryResult } from "@corewire/core/discovery";
+
+//#region src/messages.d.ts
+declare namespace messages_d_exports {
+  export { OPackMessage, addToUpNext, appSignInRequest, deregisterInterests, fetchAttentionState, fetchCurrentTopShelfItems, fetchLaunchableApps, fetchMediaControlStatus, fetchNowPlayingInfo, fetchSiriRemoteInfo, fetchSupportedActions, fetchUpNext, fetchUserAccounts, gameControllerEvent, gameControllerStart, gameControllerStop, hidCommand, hidTouchEvent, launchApp, launchUrl, markAsWatched, mediaCaptionSettingGet, mediaCaptionSettingSet, mediaControlCommand, mediaSkipBySeconds, playMedia, registerInterests, removeFromUpNext, restrictedAccessRequest, sessionStart, sessionStop, siriStart, siriStop, switchActiveUserAccount, switchUserAccount, systemInfo, tiChange, tiStart, tiStop, toggleCaptions, toggleFindingMode, toggleReduceLoudSounds, toggleSystemAppearance, touchEvent, touchStart, touchStop, tvProviderRequest, tvrcSessionStart, tvrcSessionStop };
+}
+/** An OPack message for the Companion Link stream. */
+type OPackMessage = Record<string, unknown>;
+/** The `_systemInfo` request of the startup: the identity, model and services of this controller. */
+declare function systemInfo(pairingId: Buffer, name: string, model?: string, sourceVersion?: string): OPackMessage;
+/** Starts a session with the `com.apple.tvremoteservices` service under a session id of our own. */
+declare function sessionStart(localSid: number): OPackMessage;
+declare function sessionStop(localSid: number): OPackMessage;
+/** Starts a TV Remote Control session, which `tvremoted` handles on the Apple TV. */
+declare function tvrcSessionStart(): OPackMessage;
+declare function tvrcSessionStop(): OPackMessage;
+/** One button edge of a {@link HidCommand}; `down` false sends the release. */
+declare function hidCommand(commandId: number, down: boolean): OPackMessage;
+/** Starts the virtual touchpad; the size sets its coordinate space. */
+declare function touchStart(width?: number, height?: number): OPackMessage;
+declare function touchStop(): OPackMessage;
+/**
+* A `_touchC` event, in the coordinate space of the touchpad.
+*
+* @param finger - The finger index, 0-based.
+* @param phase - A {@link TouchPhase} value.
+*/
+declare function touchEvent(finger: number, phase: number, x: number, y: number): OPackMessage;
+/**
+* A `_hidT` event, the form an Apple remote sends touchpad gestures in on the wire. Unlike
+* {@link touchEvent}, the coordinates are integers and the event carries a timestamp.
+*
+* @param finger - The finger index, 1-based.
+* @param phase - A {@link HidTouchPhase} value.
+* @param timestamp - A monotonic timestamp in nanoseconds.
+*/
+declare function hidTouchEvent(finger: number, phase: number, x: number, y: number, timestamp?: number): OPackMessage;
+/** Starts remote text input (RTI); the reply carries the keyboard session. */
+declare function tiStart(): OPackMessage;
+declare function tiStop(): OPackMessage;
+/** A `_tiC` event with serialized RTITextOperations. */
+declare function tiChange(tiD: Buffer): OPackMessage;
+/**
+* A `_mcc` request.
+*
+* @param commandId - A {@link MediaControlCommand} value.
+* @param content - Extra fields, such as the volume for `SetVolume`.
+*/
+declare function mediaControlCommand(commandId: number, content?: Record<string, unknown>): OPackMessage;
+/** Skips forward, or backward for a negative number of seconds. */
+declare function mediaSkipBySeconds(seconds: number): OPackMessage;
+declare function mediaCaptionSettingGet(): OPackMessage;
+declare function mediaCaptionSettingSet(enabled: boolean): OPackMessage;
+declare function launchApp(bundleId: string): OPackMessage;
+/** Opens a URL; the device picks the app through universal links. */
+declare function launchUrl(url: string): OPackMessage;
+/** Asks for the attention (power) state. */
+declare function fetchAttentionState(): OPackMessage;
+declare function fetchLaunchableApps(): OPackMessage;
+declare function fetchMediaControlStatus(): OPackMessage;
+declare function fetchNowPlayingInfo(): OPackMessage;
+declare function fetchSiriRemoteInfo(): OPackMessage;
+declare function fetchSupportedActions(): OPackMessage;
+declare function fetchCurrentTopShelfItems(): OPackMessage;
+declare function fetchUserAccounts(): OPackMessage;
+declare function switchUserAccount(accountId: string): OPackMessage;
+/**
+* Tells the Apple TV which iCloud account (alternate DSID) this controller is active on. An iOS
+* remote sends it during the startup.
+*/
+declare function switchActiveUserAccount(iCloudAltDSID: string): OPackMessage;
+/** Registers interest in events the device pushes, such as `_iMC` or `SystemStatus`. */
+declare function registerInterests(events: string[]): OPackMessage;
+declare function deregisterInterests(events: string[]): OPackMessage;
+declare function toggleCaptions(): OPackMessage;
+/** Light appearance when `light` is true, dark when false. */
+declare function toggleSystemAppearance(light: boolean): OPackMessage;
+declare function toggleReduceLoudSounds(enabled: boolean): OPackMessage;
+/** Turns the Find My finding mode on or off. */
+declare function toggleFindingMode(enabled: boolean): OPackMessage;
+/** @param paginationToken - Fetches the page after the one that returned it. */
+declare function fetchUpNext(paginationToken?: string): OPackMessage;
+/** @param kind - The content kind, such as movie or episode. */
+declare function addToUpNext(identifier: string, kind: string): OPackMessage;
+declare function removeFromUpNext(identifier: string, kind: string): OPackMessage;
+declare function markAsWatched(identifier: string, kind: string): OPackMessage;
+declare function playMedia(item: Record<string, unknown>): OPackMessage;
+/** Starts Siri push-to-talk. */
+declare function siriStart(): OPackMessage;
+/** Ends Siri push-to-talk. */
+declare function siriStop(): OPackMessage;
+/** One stick position (-1 to 1 per axis) and the button state, as an event without a reply. */
+declare function gameControllerEvent(x: number, y: number, isDown: boolean): OPackMessage;
+declare function gameControllerStart(): OPackMessage;
+declare function gameControllerStop(): OPackMessage;
+/**
+* Runs the sign-in of an Apple TV app through this controller, as a paired iPhone or iPad does.
+*
+* @param requestType - The kind of sign-in: `appleID`, `password` or `custom`.
+*/
+declare function appSignInRequest(bundleId: string, requestType?: string): OPackMessage;
+/** A TV provider (MVPD) sign-in request. */
+declare function tvProviderRequest(providerUrl: string, providerName: string): OPackMessage;
+/** A restricted access (parental controls) approval request. */
+declare function restrictedAccessRequest(restrictionType: string): OPackMessage;
+//#endregion
+//#region src/stream.d.ts
+/** `event` carries every incoming frame with an `_i` that settled no exchange: its name and its `_c`. */
+type StreamEventMap = {
+  readonly event: [name: string, content: unknown];
+};
+/**
+* The Companion Link socket: OPack frames of `[type:1][length:3][payload][tag:16?]`, the header
+* being the AAD once encryption is on. The nonce is the 64-bit little-endian message counter at
+* offset 0 of 12 bytes. {@link exchange} waits for the reply with the same `_x`; every other frame
+* with an `_i` becomes an `event`.
+*/
+declare class Stream extends EncryptionAwareConnection<StreamEventMap> {
+  #private;
+  constructor(context: Context, address: string, port: number);
+  /**
+  * Sends an OPack frame and resolves with the decoded reply. Pairing frames share one slot,
+  * because their replies carry no `_x`.
+  *
+  * @throws {TimeoutError} When no reply arrives in time.
+  * @throws {ConnectionClosedError} When the stream ends first.
+  */
+  exchange(type: number, message: Record<string, unknown>, timeout?: number): Promise<[number, unknown]>;
+  /**
+  * Encodes an object as OPack and sends it, with the next `_x` unless it carries one.
+  *
+  * @throws {ConnectionClosedError} When the stream has ended.
+  */
+  sendOPack(type: number, message: Record<string, unknown>): void;
+  /** Writes one frame; encrypted once encryption is on, except NoOp, which stays plaintext. */
+  send(type: number, payload: Buffer): void;
+}
+//#endregion
+//#region src/channel.d.ts
+/** A decoded reply; `_c` holds the content. */
+type Reply = Record<string, any>;
+/** Receives the `_c` of an event. */
+type EventListener = (content: unknown) => void;
+/**
+* What the groups of a session send with: encrypted requests that check the reply, events without
+* one, and the events the device sends. Listeners go when the session signal aborts.
+*/
+declare class Channel {
+  #private;
+  /** Aborts when the session ends. */
+  get signal(): AbortSignal;
+  /** Whether the socket can still carry a frame; false while the session closes. */
+  get isConnected(): boolean;
+  constructor(stream: Stream, signal: AbortSignal);
+  /**
+  * Sends a request and resolves with its reply.
+  *
+  * @throws {CommandError} When the reply carries `_em` or a non-zero `_ec`.
+  * @throws {TimeoutError} When no reply arrives in time.
+  * @throws {ConnectionClosedError} When the session ends first.
+  */
+  exchange(message: OPackMessage): Promise<Reply>;
+  /**
+  * Sends an event, which gets no reply.
+  *
+  * @throws {ConnectionClosedError} When the session has ended.
+  */
+  send(message: OPackMessage): void;
+  /** Calls the listener with the `_c` of every event with this name, until the session ends. */
+  listen(name: string, listener: EventListener): void;
+  unlisten(name: string, listener: EventListener): void;
+}
+//#endregion
+//#region src/state.d.ts
+type CompanionLinkStateEventMap = {
+  readonly attentionStateChanged: [AttentionState];
+  readonly mediaControlFlagsChanged: [flags: number, capabilities: MediaCapabilities];
+  readonly nowPlayingInfoChanged: [info: Record<string, unknown> | null];
+  readonly supportedActionsChanged: [actions: Record<string, unknown>];
+  readonly textInputChanged: [TextInputState];
+  readonly volumeAvailabilityChanged: [available: boolean];
+};
+/**
+* What a Companion Link device reports about itself: attention state, media controls, now playing,
+* supported actions and text input. A model without I/O: feed it with {@link apply}, from a session
+* or from recorded events.
+*/
+declare class CompanionLinkState extends EventEmitter<CompanionLinkStateEventMap> {
+  #private;
+  get attentionState(): AttentionState;
+  get mediaCapabilities(): MediaCapabilities;
+  /** The raw `_iMC` bitmask, see {@link MediaControlFlag}. */
+  get mediaControlFlags(): number;
+  get nowPlayingInfo(): Record<string, unknown> | null;
+  get supportedActions(): Record<string, unknown> | null;
+  get textInputState(): TextInputState;
+  get volumeAvailable(): boolean;
+  constructor();
+  /**
+  * Applies the `_c` of one event. Events the state does not track are ignored.
+  * `FetchAttentionState` takes the content of that reply and always emits, also when the state
+  * did not change, so a fresh session reports its attention state once.
+  *
+  * @throws When the content is malformed; text input falls back to its default state first.
+  */
+  apply(name: string, content: unknown): void;
+  /** Resets every value to its initial one, without events. */
+  clear(): void;
+}
+//#endregion
+//#region src/types.d.ts
+/** Where a Companion Link device listens. The port comes from discovery; it is not fixed. */
+type CompanionLinkTarget = {
+  readonly address: string;
+  readonly port: number; /** Tags the logs of the connection, usually the mDNS name. Defaults to the address. */
+  readonly id?: string; /** The TXT record from discovery, when known. */
+  readonly txt?: Readonly<Record<string, string>>;
+};
+/** How {@link connect} reaches and authenticates with the device. */
+type ConnectOptions = {
+  /** Long-term credentials from a PIN pairing, for pair-verify. The AirPlay credentials of an Apple TV work too. */readonly credentials: AccessoryCredentials; /** Logger to use. Built from {@link CompanionLinkTarget.id} and {@link identity} when omitted. */
+  readonly context?: Context; /** Overrides of the identity of the context; ignored when a context is passed. */
+  readonly identity?: DeviceIdentity;
+  /**
+  * The iCloud account (alternate DSID) to announce as active during the startup, as an iOS
+  * remote does. Without it the startup sends no `SwitchActiveUserAccountEvent`.
+  */
+  readonly activeUserAccount?: string;
+  /**
+  * The state to feed; a new one when omitted. Pass one to keep its listeners across sessions.
+  * It is fed as it is: clear it yourself when a new session should start empty.
+  */
+  readonly state?: CompanionLinkState; /** Ends the session right away, or interrupts the handshake, when aborted. */
+  readonly signal?: AbortSignal;
+};
+/** How a PIN pairing is set up. */
+type PairOptions = Pick<ConnectOptions, "context" | "identity" | "signal">;
+/**
+* Why a session ended: this side closed it (`local`), the device did (`remote`), the socket did
+* not open in time (`timeout`), or a socket or frame broke (`error`).
+*/
+type SessionCloseReason = CloseReason;
+/** Which playback controls the device offers now, from the `_iMC` flags. */
+type MediaCapabilities = {
+  readonly play: boolean;
+  readonly pause: boolean;
+  readonly nextTrack: boolean;
+  readonly previousTrack: boolean;
+  readonly fastForward: boolean;
+  readonly rewind: boolean;
+  readonly volume: boolean;
+  readonly skipForward: boolean;
+  readonly skipBackward: boolean;
+};
+/** The attention (power) state of the Apple TV. */
+type AttentionState = "unknown" | "asleep" | "screensaver" | "awake" | "idle";
+/** The remote text input (RTI) session on the Apple TV. */
+type TextInputState = {
+  /** True while a text field has focus. */readonly isActive: boolean;
+  readonly documentText: string; /** True for a password field. */
+  readonly isSecure: boolean; /** The keyboard type the field asks for. */
+  readonly keyboardType: number;
+  readonly autocorrection: boolean;
+  readonly autocapitalization: boolean;
+};
+type ButtonPressType = "DoubleTap" | "Hold" | "SingleTap";
+type LaunchableApp = {
+  /** The bundle identifier, such as `com.apple.TVMovies`. */readonly bundleId: string;
+  readonly name: string;
+};
+type UserAccount = {
+  readonly accountId: string;
+  readonly name: string;
+};
+/** The phases of the `_touchC` event, the 0-based `UITouchPhase` values. */
+declare const TouchPhase: {
+  readonly Began: 0;
+  readonly Moved: 1;
+  readonly Ended: 2;
+  readonly Cancelled: 3;
+  readonly Stationary: 4;
+};
+type TouchPhaseValue = typeof TouchPhase[keyof typeof TouchPhase];
+/** The phases of the `_hidT` event. Unlike {@link TouchPhase}, the HID touch stream on the wire is 1-based. */
+declare const HidTouchPhase: {
+  readonly Began: 1;
+  readonly Moved: 2;
+  readonly Stationary: 3;
+  readonly Ended: 4;
+  readonly Cancelled: 5;
+};
+type HidTouchPhaseValue = typeof HidTouchPhase[keyof typeof HidTouchPhase];
+type SwipeDirection = "up" | "down" | "left" | "right";
+//#endregion
+//#region src/accounts.d.ts
+/** User accounts on the device, and the experimental sign-in, TV provider and parental approval requests. */
+declare class Accounts {
+  #private;
+  constructor(channel: Channel);
+  list(): Promise<UserAccount[]>;
+  switch(accountId: string): Promise<void>;
+  /** Tells the device which iCloud account (alternate DSID) this controller is active on. */
+  switchActive(iCloudAltDSID: string): Promise<void>;
+  /** @param requestType The kind of sign-in: `appleID`, `password` or `custom`. */
+  requestAppSignIn(bundleId: string, requestType?: string): Promise<object>;
+  requestTVProvider(providerUrl: string, providerName: string): Promise<object>;
+  requestRestrictedAccess(restrictionType: string): Promise<object>;
+}
+//#endregion
+//#region src/apps.d.ts
+/** The apps on the device: listing, launching, opening a URL and the top shelf. */
+declare class Apps {
+  #private;
+  constructor(channel: Channel);
+  list(): Promise<LaunchableApp[]>;
+  launch(bundleId: string): Promise<void>;
+  /** Opens a URL; the device picks the app through universal links or the URL scheme. */
+  openUrl(url: string): Promise<void>;
+  /** The top shelf items the device shows now, as the raw reply. */
+  topShelf(): Promise<any>;
+}
+//#endregion
+//#region src/const.d.ts
+/** Siri Remote buttons, as the command ids of the `_hidC` request. */
+declare const HidCommand: {
+  readonly Up: 1;
+  readonly Down: 2;
+  readonly Left: 3;
+  readonly Right: 4;
+  readonly Menu: 5;
+  readonly Select: 6;
+  readonly Home: 7;
+  readonly VolumeUp: 8;
+  readonly VolumeDown: 9;
+  readonly Siri: 10;
+  readonly Screensaver: 11;
+  readonly Sleep: 12;
+  readonly Wake: 13;
+  readonly PlayPause: 14;
+  readonly ChannelIncrement: 15;
+  readonly ChannelDecrement: 16;
+  readonly Guide: 17;
+  readonly PageUp: 18;
+  readonly PageDown: 19;
+  readonly SkipForward: 20;
+  readonly SkipBackward: 21;
+  readonly Back: 22;
+  readonly Exit: 23;
+  readonly Info: 24;
+  readonly CaptionsToggle: 25;
+  readonly Accessibility: 26;
+  readonly InputSelect: 27;
+  readonly Mute: 29;
+  readonly Power: 30;
+};
+/** Playback and caption commands of the `_mcc` request. */
+declare const MediaControlCommand: {
+  readonly Play: 1;
+  readonly Pause: 2;
+  readonly NextTrack: 3;
+  readonly PreviousTrack: 4;
+  readonly GetVolume: 5;
+  readonly SetVolume: 6;
+  readonly SkipBy: 7;
+  readonly FastForwardBegin: 8;
+  readonly FastForwardEnd: 9;
+  readonly RewindBegin: 10;
+  readonly RewindEnd: 11;
+  readonly GetCaptionSettings: 12;
+  readonly SetCaptionSettings: 13;
+};
+/** Bit flags of the media controls the Apple TV supports right now, from the media control status. */
+declare const MediaControlFlag: {
+  readonly Play: 0x0001;
+  readonly Pause: 0x0002;
+  readonly PreviousTrack: 0x0004;
+  readonly NextTrack: 0x0008;
+  readonly FastForward: 0x0010;
+  readonly Rewind: 0x0020;
+  readonly Volume: 0x0100;
+  readonly SkipForward: 0x0200;
+  readonly SkipBackward: 0x0400;
+};
+type HidCommandKey = keyof typeof HidCommand;
+type MediaControlCommandKey = keyof typeof MediaControlCommand;
+//#endregion
+//#region src/hid.d.ts
+/** Remote buttons as HID commands, and the experimental game controller. */
+declare class Hid {
+  #private;
+  constructor(channel: Channel);
+  /** Sends one button edge: down, or up when `down` is false. */
+  command(command: HidCommandKey, down?: boolean): Promise<void>;
+  /**
+  * A full press: down and up for a single tap, that twice without a pause for a double tap,
+  * and for a hold the release after `holdDelayMs`.
+  */
+  press(command: HidCommandKey, type?: ButtonPressType, holdDelayMs?: number): Promise<void>;
+  gameControllerStart(): Promise<void>;
+  gameControllerStop(): Promise<void>;
+  /** One stick position (-1 to 1 per axis) and the button state. */
+  sendGameControllerEvent(x: number, y: number, isDown: boolean): void;
+}
+//#endregion
+//#region src/interests.d.ts
+/** The events the device pushes once interest in them is registered, such as `_iMC` or `SystemStatus`. */
+declare class Interests {
+  #private;
+  constructor(channel: Channel);
+  /** Registers interest in the events, in one `_interest` event. */
+  register(events: string[]): void;
+  /** Deregisters interest in the events; nothing when the socket is gone, so a teardown cannot fail on it. */
+  deregister(events: string[]): void;
+  /** Listens to an event, until the session ends, and registers interest in it. */
+  subscribe(event: string, listener: EventListener): void;
+  /** Stops listening, when a listener is given, and deregisters interest in the event. */
+  unsubscribe(event: string, listener?: EventListener): void;
+}
+//#endregion
+//#region src/media.d.ts
+/**
+* Media control over `_mcc`, what the device reports about playback, and playing a media item.
+* The flags follow the `_iMC` events; the state reports a change.
+*/
+declare class Media {
+  #private;
+  get capabilities(): MediaCapabilities;
+  /** The raw `_iMC` bitmask, see `MediaControlFlag`. */
+  get flags(): number;
+  get nowPlayingInfo(): Record<string, unknown> | null;
+  get supportedActions(): Record<string, unknown> | null;
+  get volumeAvailable(): boolean;
+  constructor(channel: Channel, state: CompanionLinkState);
+  /** @param content Extra fields of the command, such as the volume for `SetVolume`. */
+  command(command: MediaControlCommandKey, content?: Record<string, unknown>): Promise<object>;
+  /** Skips forward, or backward for a negative number of seconds. */
+  skipBy(seconds: number): Promise<object>;
+  /** Asks for the media control status; the reply is not used. */
+  fetchControlStatus(): Promise<void>;
+  /** The now playing information, as the raw reply. */
+  fetchNowPlayingInfo(): Promise<any>;
+  /** Asks for the supported actions; the reply is not used. */
+  fetchSupportedActions(): Promise<void>;
+  /** Plays a media item, described by the OPack dictionary the device expects. */
+  play(item: Record<string, unknown>): Promise<void>;
+}
+//#endregion
+//#region src/power.d.ts
+/**
+* Attention state and the power buttons. The state follows the `SystemStatus` and `TVSystemStatus`
+* events; its `attentionStateChanged` event reports a change.
+*/
+declare class Power {
+  #private;
+  /** The attention state the device reported last. */
+  get attentionState(): AttentionState;
+  constructor(channel: Channel, hid: Hid, state: CompanionLinkState);
+  /** Asks the device for its attention state; the state is left as it is. */
+  fetch(): Promise<AttentionState>;
+  isAwake(): Promise<boolean>;
+  /** Presses the Wake button. */
+  wake(): Promise<void>;
+  /** Presses the Sleep button. */
+  sleep(): Promise<void>;
+}
+//#endregion
+//#region src/system.d.ts
+/** System settings, Siri and the Up Next queue. */
+declare class System {
+  #private;
+  constructor(channel: Channel);
+  toggleCaptions(): Promise<void>;
+  /** The caption settings, over `_mcc`. */
+  getCaptionSetting(): Promise<object>;
+  setCaptionSetting(enabled: boolean): Promise<object>;
+  /** Light appearance when true, dark when false. */
+  setAppearance(light: boolean): Promise<void>;
+  setReduceLoudSounds(enabled: boolean): Promise<void>;
+  setFindingMode(enabled: boolean): Promise<void>;
+  /** Push-to-talk begin; see `supportsSiriPTT` on the session. */
+  siriStart(): Promise<void>;
+  siriStop(): Promise<void>;
+  /** What the device knows about the paired Siri Remote, from the plist in the reply. */
+  siriRemoteInfo(): Promise<any>;
+  /** The Up Next queue, as the raw reply. */
+  fetchUpNext(paginationToken?: string): Promise<any>;
+  addToUpNext(identifier: string, kind: string): Promise<void>;
+  removeFromUpNext(identifier: string, kind: string): Promise<void>;
+  markAsWatched(identifier: string, kind: string): Promise<void>;
+}
+//#endregion
+//#region src/text.d.ts
+/**
+* Remote text input into the focused field. Operations run one at a time; each one starts the
+* text input session anew for the keyboard session UUID. An operation queued before the field
+* changed, stopped or the session ended fails instead of typing into the wrong field.
+*/
+declare class Text {
+  #private;
+  /** The text input session the device reported last. */
+  get state(): TextInputState;
+  constructor(channel: Channel, state: CompanionLinkState);
+  /** Replaces the text of the field. */
+  set(text: string): Promise<void>;
+  append(text: string): Promise<void>;
+  clear(): Promise<void>;
+  /**
+  * Clears the field when asked, then inserts the text when there is any.
+  *
+  * @throws {Error} When no field has focus, or the field changed before the operation ran.
+  */
+  command(text: string, clearPreviousInput: boolean): Promise<string | null>;
+  /** Starts the text input session; the reply carries the keyboard session in `_c._tiD`. */
+  start(): Promise<Record<string, any>>;
+  stop(): Promise<void>;
+}
+//#endregion
+//#region src/touch.d.ts
+/** The virtual touchpad. Coordinates run from 0 to 1000 on both axes. */
+declare class Touch {
+  #private;
+  constructor(channel: Channel, hid: Hid);
+  /**
+  * Sends a `_touchC` event. Kept for protocol work: tvOS registers no handler for it, so
+  * {@link sendHid} is what reaches the device.
+  *
+  * @param finger The finger index, 0-based.
+  * @param phase A `TouchPhase` value.
+  */
+  send(finger: number, phase: number, x: number, y: number): void;
+  /**
+  * Sends a `_hidT` event, the form the HID daemon of the Apple TV listens for.
+  *
+  * @param finger The finger index, 1-based.
+  * @param phase A {@link HidTouchPhase} value.
+  */
+  sendHid(finger: number, phase: number, x: number, y: number): void;
+  /**
+  * Taps the touch surface, which selects whatever has focus. The HID touch device reports
+  * contact and position only, so a touch that lands and lifts moves no focus and clicks
+  * nothing; a real remote sends the Select button for a tap.
+  *
+  * @param holdMs How long to hold, in milliseconds. Omit for a plain tap.
+  */
+  tap(holdMs?: number): Promise<void>;
+  /** Began, at least four Moved samples spread over `duration` milliseconds, then Ended at the end point. */
+  swipe(direction: SwipeDirection, duration?: number): Promise<void>;
+}
+//#endregion
+//#region src/session.d.ts
+type EventMap = {
+  closed: [reason: SessionCloseReason, error?: Error];
+};
+type SessionParts = {
+  readonly target: CompanionLinkTarget;
+  readonly context: Context;
+  readonly stream: Stream;
+  readonly state: CompanionLinkState;
+  readonly signal?: AbortSignal;
+};
+/**
+* The device or the socket ended the connection after it opened and before the session was
+* ready, which a caller may want to treat like a session that dropped.
+*/
+declare class SetupClosedError extends ConnectionClosedError {
+  readonly reason: SessionCloseReason;
+  constructor(reason: SessionCloseReason);
+}
+/**
+* Connects to a Companion Link device and returns a ready session. It runs TCP, pair-verify and
+* encryption, then the startup: `_systemInfo`, `_sessionStart`, `TVRCSessionStart`, optionally
+* `SwitchActiveUserAccountEvent`, `_touchStart` and `_tiStart` as requests, the heartbeat, one
+* `_interest` event per state event, and the attention state and media control status.
+*
+* @throws {CredentialsError} Without credentials.
+* @throws {PairingError} When pair-verify fails.
+* @throws {ConnectionClosedError} When the signal aborts or the device closes during the handshake.
+*/
+declare function connect(target: CompanionLinkTarget, options: ConnectOptions): Promise<CompanionLinkSession>;
+/**
+* One authenticated Companion Link connection, with its methods in groups. It lives once: it ends
+* exactly once, with a reason, and then its {@link signal} aborts and the heartbeat, listeners and
+* pending requests go with it. Requests on an ended session fail with {@link ConnectionClosedError}.
+*/
+declare class CompanionLinkSession extends EventEmitter<EventMap> {
+  #private;
+  /** Why the session ended, or undefined while it is open. */
+  get closeReason(): SessionCloseReason | undefined;
+  get context(): Context;
+  get isOpen(): boolean;
+  /** Aborts with a {@link ConnectionClosedError} when the session ends. */
+  get signal(): AbortSignal;
+  /** The source version the device reported in `_systemInfo`, such as `715.2`; `0` when it sent none. */
+  get sourceVersion(): string;
+  /** The encrypted OPack stream, for raw frames. */
+  get stream(): Stream;
+  /** Media control needs source version 250.3 or later. */
+  get supportsMediaControl(): boolean;
+  /** Siri push-to-talk needs source version 600.20 or later. */
+  get supportsSiriPTT(): boolean;
+  /** Remote text input needs source version 340.15 or later. */
+  get supportsTextInput(): boolean;
+  get target(): CompanionLinkTarget;
+  readonly accounts: Accounts;
+  readonly apps: Apps;
+  readonly hid: Hid;
+  readonly interests: Interests;
+  readonly media: Media;
+  readonly power: Power;
+  readonly state: CompanionLinkState;
+  readonly system: System;
+  readonly text: Text;
+  readonly touch: Touch;
+  /** Use {@link connect}; a session starts from a verified, encrypted stream. */
+  constructor(parts: SessionParts);
+  /**
+  * Ends the session gracefully: stops the heartbeat, deregisters the interests, stops text
+  * input, touch, the remote control session and the service session (each failure ignored),
+  * then closes the socket. Resolves once it is closed; a peer that does not finish within
+  * {@link CLOSE_TIMEOUT} gets its socket destroyed.
+  */
+  close(): Promise<void>;
+  /** Sends a NoOp frame, which stays plaintext. */
+  noOp(): void;
+}
+//#endregion
+//#region src/pairing.d.ts
+type PairM1 = Awaited<ReturnType<PairSetup["m1"]>>;
+/**
+* Pair-verify over OPack frames, followed by the channel keys. The HKDF info strings are named
+* from the device's side: it encrypts with `ServerEncrypt-main`, our read key.
+*/
+/**
+* Starts a PIN pairing: connects and sends pair-setup M1, upon which the device shows its PIN.
+* Finish with {@link PinPairing.pin}, which returns the long-term credentials.
+*
+* @throws {PairingError} When the device refuses to start pairing.
+* @throws {ConnectionClosedError} When the signal aborts first.
+*/
+declare function pair(target: CompanionLinkTarget, options?: PairOptions): Promise<PinPairing>;
+/** A PIN pairing whose PIN the device shows now. One connection, used once. */
+declare class PinPairing {
+  #private;
+  /** Aborts when the pairing connection closes. */
+  get signal(): AbortSignal;
+  constructor(stream: Stream, setup: PairSetup, m1: PairM1);
+  /**
+  * Runs pair-setup M2 to M6 with the PIN from the screen. The connection stays open; call
+  * {@link close} when done.
+  *
+  * @throws {PairingError} When a step fails or the PIN is wrong.
+  */
+  pin(code: string): Promise<AccessoryCredentials>;
+  /** Closes the pairing connection. */
+  close(): void;
+}
+//#endregion
+//#region src/discovery.d.ts
+declare const COMPANION_LINK_SERVICE = "_companion-link._tcp.local";
+/** Finds the devices on the local network that accept Companion Link connections. */
+declare function discover(options?: DiscoverOptions): Promise<DiscoveryResult[]>;
+/** The target of a discovery result. Reads the address, the port, the id and the TXT record only. */
+declare function toTarget(result: DiscoveryResult): CompanionLinkTarget;
+//#endregion
+//#region src/frame.d.ts
+/** The first byte of every frame header; it decides how the payload is parsed and routed. */
+declare const FrameType: {
+  readonly Unknown: 0;
+  readonly NoOp: 1;
+  readonly PairSetupStart: 3;
+  readonly PairSetupNext: 4;
+  readonly PairVerifyStart: 5;
+  readonly PairVerifyNext: 6;
+  readonly OPackUnencrypted: 7;
+  readonly OPackEncrypted: 8;
+  readonly OPackPacked: 9;
+  readonly PairingRequest: 10;
+  readonly PairingResponse: 11;
+  readonly SessionStartRequest: 16;
+  readonly SessionStartResponse: 17;
+  readonly SessionData: 18;
+  readonly FamilyIdentityRequest: 32;
+  readonly FamilyIdentityResponse: 33;
+  readonly FamilyIdentityUpdate: 34;
+};
+/** The `_t` field of an OPack message. */
+declare const MessageType: {
+  readonly Event: 1;
+  readonly Request: 2;
+  readonly Response: 3;
+};
+/** Frame types with an OPack payload. */
+declare const OPackFrameTypes: number[];
+/** Pair-setup and pair-verify frames. They have no `_x` exchange id, so they get a queue id of their own. */
+declare const PairingFrameTypes: number[];
+//#endregion
+//#region src/utils.d.ts
+/** Maps the numeric attention state of the Apple TV to its name; `unknown` for any other value. */
+declare function convertAttentionState(state: number): AttentionState;
+//#endregion
+export { Accounts, Apps, type AttentionState, type ButtonPressType, COMPANION_LINK_SERVICE, Channel, CompanionLinkSession, CompanionLinkState, type CompanionLinkStateEventMap, type CompanionLinkTarget, type ConnectOptions, type EventListener, FrameType, Hid, HidCommand, type HidCommandKey, HidTouchPhase, type HidTouchPhaseValue, Interests, type LaunchableApp, Media, type MediaCapabilities, MediaControlCommand, type MediaControlCommandKey, MediaControlFlag, MessageType, messages_d_exports as Messages, OPackFrameTypes, type PairOptions, PairingFrameTypes, PinPairing, Power, type Reply, type SessionCloseReason, SetupClosedError, Stream, type StreamEventMap, type SwipeDirection, System, Text, type TextInputState, Touch, TouchPhase, type TouchPhaseValue, type UserAccount, connect, convertAttentionState, discover, pair, toTarget };