@basmilius/apple-companion-link 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -26,6 +26,16 @@ declare const HidCommand: {
   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;
 };
 /**
 * Media control command identifiers for playback and caption control.
@@ -303,8 +313,8 @@ declare class Protocol {
   * NoOp frames are always sent unencrypted regardless of encryption state.
   */
   noOp(): void;
-  /** The Apple TV's reported protocol source version number (e.g. `715.2`). */
-  get sourceVersion(): number;
+  /** The Apple TV's reported protocol source version string (e.g. `715.2`). */
+  get sourceVersion(): string;
   /** Whether this Apple TV supports media control commands (sourceVersion >= 250.3). */
   get supportsMediaControl(): boolean;
   /** Whether this Apple TV supports remote text input (sourceVersion >= 340.15). */
@@ -418,6 +428,24 @@ declare class Protocol {
   */
   mediaControlCommand(command: MediaControlCommandKey, content?: Record<string, unknown>): Promise<object>;
   /**
+  * Skips forward or backward by a given number of seconds.
+  *
+  * @param seconds - Number of seconds to skip (positive = forward, negative = backward).
+  */
+  skipBySeconds(seconds: number): Promise<object>;
+  /**
+  * Gets the current caption/subtitle settings.
+  *
+  * @returns The caption settings response.
+  */
+  getCaptionSetting(): Promise<object>;
+  /**
+  * Enables or disables captions/subtitles.
+  *
+  * @param enabled - Whether captions should be enabled.
+  */
+  setCaptionSetting(enabled: boolean): Promise<object>;
+  /**
   * Launches an app on the Apple TV by its bundle identifier.
   *
   * @param bundleId - The bundle identifier of the app to launch.
@@ -528,6 +556,21 @@ declare class Protocol {
   */
   toggleFindingMode(enabled: boolean): Promise<void>;
   /**
+  * Wakes the Apple TV by sending a wake HID key.
+  * Checks the attention state first and only sends if the device is idle.
+  */
+  wakeDevice(): Promise<void>;
+  /**
+  * Puts the Apple TV to sleep.
+  */
+  sleepDevice(): Promise<void>;
+  /**
+  * Checks whether the Apple TV is currently awake (actively in use).
+  *
+  * @returns `true` if the device is awake/active, `false` if idle or unknown.
+  */
+  isAwake(): Promise<boolean>;
+  /**
   * Fetches the Up Next queue from the Apple TV.
   *
   * @param paginationToken - Optional token to fetch the next page of results.
@@ -570,6 +613,46 @@ declare class Protocol {
   * Deactivates Siri (releases push-to-talk) on the Apple TV.
   */
   siriStop(): Promise<void>;
+  /**
+  * Starts a game controller session on the Apple TV.
+  */
+  gameControllerStart(): Promise<void>;
+  /**
+  * Stops the game controller session.
+  */
+  gameControllerStop(): Promise<void>;
+  /**
+  * Sends a game controller event with analog stick position and button state.
+  *
+  * @param x - X coordinate (-1.0 to 1.0).
+  * @param y - Y coordinate (-1.0 to 1.0).
+  * @param isDown - Whether the button is pressed.
+  */
+  sendGameControllerEvent(x: number, y: number, isDown: boolean): void;
+  /**
+  * Initiates an app sign-in proxy flow, allowing the Apple TV app
+  * to authenticate via the paired companion device.
+  *
+  * @param bundleId - The bundle identifier of the app requesting sign-in.
+  * @param requestType - The sign-in method ('appleID', 'password', or 'custom').
+  * @returns The sign-in response from the Apple TV.
+  */
+  requestAppSignIn(bundleId: string, requestType?: string): Promise<object>;
+  /**
+  * Initiates a TV provider (MVPD) authentication flow on the Apple TV.
+  *
+  * @param providerUrl - The provider's authentication URL.
+  * @param providerName - The provider's display name.
+  * @returns The provider auth response.
+  */
+  requestTVProvider(providerUrl: string, providerName: string): Promise<object>;
+  /**
+  * Sends a restricted access (parental controls) approval request.
+  *
+  * @param restrictionType - The type of restriction being requested.
+  * @returns The approval response.
+  */
+  requestRestrictedAccess(restrictionType: string): Promise<object>;
 }
 //#endregion
 //#region src/frame.d.ts
@@ -629,7 +712,7 @@ declare const PairingFrameTypes: number[];
 */
 declare function convertAttentionState(state: number): AttentionState;
 declare namespace messages_d_exports {
-  export { addToUpNext, buildRtiClearPayload, buildRtiInputPayload, deregisterInterests, fetchAttentionState, fetchLaunchableApps, fetchMediaControlStatus, fetchNowPlayingInfo, fetchSiriRemoteInfo, fetchSiriStatus, fetchSupportedActions, fetchUpNext, fetchUserAccounts, hidCommand, launchApp, launchUrl, markAsWatched, mediaControlCommand, ping, playMedia, publishPresence, registerInterests, removeFromUpNext, sessionStart, sessionStop, siriStart, siriStop, switchUserAccount, systemInfo, tiChange, tiStart, tiStop, toggleCaptions, toggleFindingMode, toggleReduceLoudSounds, toggleSystemAppearance, touchEvent, touchStart, touchStop, tvrcSessionStart, tvrcSessionStop };
+  export { addToUpNext, appSignInRequest, buildRtiClearPayload, buildRtiInputPayload, deregisterInterests, fetchAttentionState, fetchLaunchableApps, fetchMediaControlStatus, fetchNowPlayingInfo, fetchSiriRemoteInfo, fetchSiriStatus, fetchSupportedActions, fetchUpNext, fetchUserAccounts, gameControllerEvent, gameControllerStart, gameControllerStop, hidCommand, launchApp, launchUrl, markAsWatched, mediaCaptionSettingGet, mediaCaptionSettingSet, mediaControlCommand, mediaSkipBySeconds, ping, playMedia, publishPresence, registerInterests, removeFromUpNext, restrictedAccessRequest, sessionStart, sessionStop, siriStart, siriStop, switchUserAccount, systemInfo, tiChange, tiStart, tiStop, toggleCaptions, toggleFindingMode, toggleReduceLoudSounds, toggleSystemAppearance, touchEvent, touchStart, touchStop, tvProviderRequest, tvrcSessionStart, tvrcSessionStop };
 }
 /** An OPack-encoded message to be sent over the Companion Link stream. */
 type OPackMessage = Record<string, unknown>;
@@ -756,6 +839,26 @@ declare function buildRtiInputPayload(sessionUUID: Buffer, text: string): ArrayB
 */
 declare function mediaControlCommand(commandId: number, content?: Record<string, unknown>): OPackMessage;
 /**
+* Builds a media control command to skip forward or backward by a given number of seconds.
+*
+* @param seconds - Number of seconds to skip (positive = forward, negative = backward).
+* @returns The skip-by-seconds request message.
+*/
+declare function mediaSkipBySeconds(seconds: number): OPackMessage;
+/**
+* Builds a message to get the current caption/subtitle settings.
+*
+* @returns The get caption settings request message.
+*/
+declare function mediaCaptionSettingGet(): OPackMessage;
+/**
+* Builds a message to enable or disable captions/subtitles.
+*
+* @param enabled - Whether captions should be enabled.
+* @returns The set caption settings request message.
+*/
+declare function mediaCaptionSettingSet(enabled: boolean): OPackMessage;
+/**
 * Builds a message to launch an app by its bundle identifier.
 *
 * @param bundleId - The bundle identifier of the app to launch (e.g. `com.apple.TVMovies`).
@@ -923,5 +1026,52 @@ declare function siriStop(): OPackMessage;
 * @returns The publish presence request message.
 */
 declare function publishPresence(): OPackMessage;
+/**
+* Builds a game controller event message with analog stick position.
+* Sent as a fire-and-forget event (no response expected).
+*
+* @param x - X coordinate of the analog stick (-1.0 to 1.0).
+* @param y - Y coordinate of the analog stick (-1.0 to 1.0).
+* @param isDown - Whether the button is pressed.
+* @returns The game controller event message.
+*/
+declare function gameControllerEvent(x: number, y: number, isDown: boolean): OPackMessage;
+/**
+* Builds a game controller session start message.
+*
+* @returns The game controller start request message.
+*/
+declare function gameControllerStart(): OPackMessage;
+/**
+* Builds a game controller session stop message.
+*
+* @returns The game controller stop request message.
+*/
+declare function gameControllerStop(): OPackMessage;
+/**
+* Builds a request to proxy an app sign-in flow through the companion device.
+* Used when an Apple TV app requests authentication via a paired iPhone/iPad.
+*
+* @param bundleId - The bundle identifier of the app requesting sign-in.
+* @param requestType - The type of sign-in request ('appleID', 'password', or 'custom').
+* @returns The app sign-in request message.
+*/
+declare function appSignInRequest(bundleId: string, requestType?: string): OPackMessage;
+/**
+* Builds a TV provider authentication request.
+* Used for MVPD (Multichannel Video Programming Distributor) sign-in on Apple TV.
+*
+* @param providerUrl - The provider's authentication URL.
+* @param providerName - The provider's display name.
+* @returns The TV provider request message.
+*/
+declare function tvProviderRequest(providerUrl: string, providerName: string): OPackMessage;
+/**
+* Builds a restricted access (parental controls) approval request.
+*
+* @param restrictionType - The type of restriction being requested.
+* @returns The restricted access request message.
+*/
+declare function restrictedAccessRequest(restrictionType: string): OPackMessage;
 //#endregion
-export { AttentionState, ButtonPressType, messages_d_exports as CompanionLinkMessage, FrameType, HidCommand, HidCommandKey, LaunchableApp, MediaControlCommand, MediaControlCommandKey, MediaControlFlag, MessageType, OPackFrameTypes, Pairing, PairingFrameTypes, Protocol, Stream, SwipeDirection, TextInputState, TouchPhase, TouchPhaseValue, UserAccount, Verify, convertAttentionState };
+export { type AttentionState, type ButtonPressType, messages_d_exports as CompanionLinkMessage, FrameType, HidCommand, type HidCommandKey, type LaunchableApp, MediaControlCommand, type MediaControlCommandKey, MediaControlFlag, MessageType, OPackFrameTypes, Pairing, PairingFrameTypes, Protocol, Stream, type SwipeDirection, type TextInputState, TouchPhase, type TouchPhaseValue, type UserAccount, Verify, convertAttentionState };