@kud/gtv 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erwann Mest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+<div align="center">
+
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat-square&logo=node.js&logoColor=white)
+![npm](https://img.shields.io/npm/v/%40kud%2Fgtv?style=flat-square&color=CB3837)
+![MIT](https://img.shields.io/badge/licence-MIT-22C55E?style=flat-square)
+
+**Google TV control library — device store, discovery, pairing, and a stateful remote session.**
+
+[Features](#-features) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Development](#-development)
+
+</div>
+
+## 🌟 Features
+
+- 🔍 **mDNS Discovery** — finds every Google TV on the local network via `dns-sd`; returns pure data, no side effects
+- 🔐 **Dependency-injected Pairing** — `onSecret` is a callback you supply (terminal `readline`, MCP round-trip, Tauri dialog…); the library never touches I/O itself
+- 📡 **Stateful Session** — `createSession()` returns an `EventEmitter` that reduces the underlying protocol stream to a single observable `SessionState`; subscribe with `.on("change", state => …)`
+- ⚡ **One-shot Helpers** — `sendKey`, `launchApp`, `connect`, `withRemote` for scripts that don't need a long-lived connection
+- 📱 **App Catalog** — curated `APPS` list with `findApp`, `listApps`, and `appLink` (builds the reliable `market://launch?id=<package>` URI)
+- 🗄️ **Shared Config Store** — reads and writes `~/.config/gtv/config.json`; all consumers (`gtv-cli`, `mcp-gtv`, `gtv-app`) share one device registry
+- 🔑 **Full Keycode Surface** — `KEYS`, `KEY_LABELS`, and re-exported `RemoteKeyCode` / `RemoteDirection` so consumers need only depend on `@kud/gtv`
+
+## 🚀 Quick Start
+
+```sh
+npm install @kud/gtv
+```
+
+### Discover and pair
+
+```ts
+import { discover, pair } from "@kud/gtv"
+
+const [tv] = await discover()
+
+await pair({
+  host: tv.host,
+  hostname: tv.hostname,
+  port: tv.port,
+  name: tv.name,
+  onSecret: async () => promptUserForPin(), // PIN displayed on the TV screen
+})
+```
+
+### Drive a stateful session
+
+```ts
+import { createSession, KEYS } from "@kud/gtv"
+
+const session = createSession() // uses the currently configured device
+session.on("change", (state) => console.log(state))
+
+session.sendKey(KEYS.home)
+session.typeText("interstellar")
+session.launchApp("market://launch?id=com.netflix.ninja")
+session.stop()
+```
+
+### One-shot commands
+
+```ts
+import { sendKey, launchApp, findApp, appLink, KEYS } from "@kud/gtv"
+
+await sendKey(KEYS.mute)
+
+const netflix = findApp("netflix")
+if (netflix) await launchApp(appLink(netflix))
+```
+
+## 📖 API Reference
+
+### Discovery
+
+| Export     | Signature                           | Description                                         |
+| ---------- | ----------------------------------- | --------------------------------------------------- |
+| `discover` | `() => Promise<DiscoveredDevice[]>` | mDNS scan; returns every Google TV found on the LAN |
+
+### Pairing
+
+| Export | Signature                                       | Description                                                         |
+| ------ | ----------------------------------------------- | ------------------------------------------------------------------- |
+| `pair` | `(options: PairOptions) => Promise<PairResult>` | Full pairing flow; `onSecret` is called with the PIN entry callback |
+
+`PairOptions`:
+
+| Field      | Type                           | Required | Description                                     |
+| ---------- | ------------------------------ | -------- | ----------------------------------------------- |
+| `host`     | `string`                       | ✓        | IP address of the TV                            |
+| `hostname` | `string`                       |          | Hostname (from mDNS)                            |
+| `port`     | `number`                       |          | Remote port (default `6466`)                    |
+| `name`     | `string`                       |          | Friendly device name                            |
+| `onSecret` | `() => Promise<string>`        | ✓        | Resolves the PIN shown on screen                |
+| `onStatus` | `(status: PairStatus) => void` |          | Progress callback                               |
+| `save`     | `boolean`                      |          | Persist device to config store (default `true`) |
+
+### Session
+
+| Export          | Signature                      | Description                         |
+| --------------- | ------------------------------ | ----------------------------------- |
+| `createSession` | `(device?: Device) => Session` | Long-lived, event-driven connection |
+
+`Session` extends `EventEmitter`:
+
+| Member             | Type                                            | Description                                                  |
+| ------------------ | ----------------------------------------------- | ------------------------------------------------------------ |
+| `state`            | `SessionState`                                  | Current snapshot (connected, powered, volume, currentApp, …) |
+| `sendKey`          | `(keyCode: number, direction?: number) => void` | Send a remote keypress                                       |
+| `typeText`         | `(text: string) => void`                        | IME text input                                               |
+| `launchApp`        | `(link: string) => void`                        | Open an app by URI                                           |
+| `stop`             | `() => void`                                    | Tear down the connection                                     |
+| `on("change", cb)` | —                                               | Fires on every state update                                  |
+| `on("error", cb)`  | —                                               | Fires on connection errors                                   |
+
+### One-shot helpers
+
+| Export                                  | Description                                      |
+| --------------------------------------- | ------------------------------------------------ |
+| `connect(device?)`                      | Opens a raw `AndroidRemote`, resolves when ready |
+| `withRemote(fn, device?)`               | Runs `fn(remote)` then closes the connection     |
+| `sendKey(keyCode, direction?, device?)` | One-shot key send                                |
+| `launchApp(link, device?)`              | One-shot app launch                              |
+
+### App catalog
+
+| Export     | Signature                                  | Description                                                             |
+| ---------- | ------------------------------------------ | ----------------------------------------------------------------------- |
+| `APPS`     | `AppEntry[]`                               | Curated list (Netflix, YouTube, Prime Video, Plex, Disney+, Spotify, …) |
+| `listApps` | `() => AppEntry[]`                         | Returns `APPS`                                                          |
+| `findApp`  | `(query: string) => AppEntry \| undefined` | Case-insensitive match on `id` or display name                          |
+| `appLink`  | `(app: AppEntry) => string`                | Builds `market://launch?id=<package>` URI                               |
+
+### Config store
+
+Config lives at `~/.config/gtv/config.json` and is shared across all consumers.
+
+| Export                    | Description                      |
+| ------------------------- | -------------------------------- |
+| `readConfig`              | Read the full config file        |
+| `listDevices`             | All paired devices               |
+| `getCurrentDevice`        | The active device                |
+| `findDevice(query)`       | Find by host, name, or hostname  |
+| `upsertDevice(device)`    | Insert or update a device entry  |
+| `setCurrentDevice(host)`  | Mark a device as active          |
+| `removeDevices(hosts)`    | Delete one or more devices       |
+| `readPreferences`         | Read the preferences block       |
+| `writePreferences(prefs)` | Write the preferences block      |
+| `CONFIG_PATH`             | Absolute path to the config file |
+
+### Keycodes
+
+| Export            | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `KEYS`            | Map of friendly names → `RemoteKeyCode` values  |
+| `KEY_LABELS`      | Map of `RemoteKeyCode` values → display strings |
+| `RemoteKeyCode`   | Re-export from `@kud/androidtv-remote`          |
+| `RemoteDirection` | Re-export from `@kud/androidtv-remote`          |
+| `setDebug`        | Enable protocol-level debug logging             |
+
+## 🔧 Development
+
+```
+gtv/
+├── src/
+│   ├── index.ts        # Public surface
+│   ├── session.ts      # Stateful Session (EventEmitter)
+│   ├── client.ts       # One-shot helpers
+│   ├── discovery.ts    # mDNS via dns-sd
+│   ├── pairing.ts      # Pairing flow
+│   ├── config.ts       # Device store + preferences
+│   ├── apps.ts         # App catalog + appLink
+│   ├── keycodes.ts     # KEYS / KEY_LABELS
+│   └── types.ts        # SessionState, VolumeState
+└── dist/               # Compiled output (tsup)
+```
+
+```sh
+git clone https://github.com/kud/gtv.git
+cd gtv
+npm install
+npm run build
+```
+
+| Script                | Description                 |
+| --------------------- | --------------------------- |
+| `npm run build`       | Compile with tsup           |
+| `npm run build:watch` | Compile in watch mode       |
+| `npm run typecheck`   | Type-check without emitting |
+| `npm run clean`       | Delete `dist/`              |
+
+**Node.js ≥ 22** required.
+
+## 🏗 Tech Stack
+
+| Package                                                            | Role                                                                |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| [`@kud/androidtv-remote`](https://github.com/kud/androidtv-remote) | Protocol layer — TLS socket, protobuf codec, key/text/app-link send |
+| [`tsup`](https://github.com/egoist/tsup)                           | Zero-config ESM bundler                                             |
+| [`typescript`](https://www.typescriptlang.org/)                    | Type safety across the entire public API                            |
+
+---
+
+MIT © [kud](https://github.com/kud) — Made with ❤️

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { AndroidRemote, VolumeState, Certificate } from '@kud/androidtv-remote';
+export { RemoteDirection, RemoteKeyCode, VolumeState, setDebug } from '@kud/androidtv-remote';
+import EventEmitter from 'node:events';
+
+declare const CONFIG_PATH: string;
+type Cert = {
+    key: string;
+    cert: string;
+};
+type Device = {
+    host: string;
+    port?: number;
+    name?: string;
+    cert?: Cert;
+};
+type Preferences = Record<string, unknown>;
+type Store = {
+    version: 2;
+    currentHost: string | null;
+    devices: Device[];
+    preferences?: Preferences;
+};
+type Config = Device;
+declare const readStore: () => Store;
+declare const listDevices: () => Device[];
+declare const getCurrentDevice: () => Device | null;
+declare const findDevice: (query: string) => Device | null;
+declare const upsertDevice: (device: Device, { makeCurrent }?: {
+    makeCurrent?: boolean;
+}) => void;
+declare const setCurrentDevice: (host: string) => boolean;
+declare const deleteConfig: () => boolean;
+declare const removeDevices: (hosts: string[]) => void;
+declare const readPreferences: () => Preferences;
+declare const writePreferences: (partial: Preferences) => Preferences;
+declare const readConfig: () => Config | null;
+
+declare const KEYS: Record<string, number>;
+declare const KEY_LABELS: Record<string, string>;
+
+declare const connect: () => Promise<AndroidRemote>;
+declare const withRemote: (fn: (remote: AndroidRemote) => void) => Promise<void>;
+declare const sendKey: (keyCode: number) => Promise<void>;
+declare const launchApp: (deeplink: string) => Promise<void>;
+
+interface SessionState {
+    tvName: string | null;
+    host: string | null;
+    connected: boolean;
+    powered: boolean | null;
+    volume: VolumeState | null;
+    currentApp: string | null;
+    error: string | null;
+}
+
+interface Session extends EventEmitter {
+    readonly state: SessionState;
+    sendKey(keyCode: number, direction?: number): void;
+    typeText(text: string): void;
+    launchApp(link: string): void;
+    stop(): void;
+    on(event: "change", listener: (state: SessionState) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+}
+declare const createSession: (device?: Device) => Session;
+
+interface DiscoveredDevice {
+    name: string;
+    host: string;
+    hostname: string;
+    port: number;
+}
+declare const discover: (opts?: {
+    timeout?: number;
+}) => Promise<DiscoveredDevice[]>;
+
+type PairStatus = "connecting" | "awaiting-pin" | "pairing" | "paired";
+interface PairOptions {
+    host: string;
+    hostname?: string;
+    port?: number;
+    name?: string;
+    serviceName?: string;
+    onSecret: () => Promise<string>;
+    onStatus?: (status: PairStatus) => void;
+    save?: boolean;
+}
+interface PairResult {
+    cert: Certificate;
+    device: Device;
+}
+declare const pair: (opts: PairOptions) => Promise<PairResult>;
+
+interface AppEntry {
+    id: string;
+    name: string;
+    packageName: string;
+    link?: string;
+}
+declare const APPS: AppEntry[];
+declare const appLink: (app: AppEntry) => string;
+declare const findApp: (query: string) => AppEntry | undefined;
+declare const listApps: () => AppEntry[];
+
+export { APPS, type AppEntry, CONFIG_PATH, type Cert, type Config, type Device, type DiscoveredDevice, KEYS, KEY_LABELS, type PairOptions, type PairResult, type PairStatus, type Preferences, type Session, type SessionState, type Store, appLink, connect, createSession, deleteConfig, discover, findApp, findDevice, getCurrentDevice, launchApp, listApps, listDevices, pair, readConfig, readPreferences, readStore, removeDevices, sendKey, setCurrentDevice, upsertDevice, withRemote, writePreferences };

package/dist/index.js

@@ -0,0 +1,438 @@
+// src/index.ts
+import { RemoteKeyCode as RemoteKeyCode2, RemoteDirection, setDebug } from "@kud/androidtv-remote";
+
+// src/config.ts
+import fs from "fs";
+import path from "path";
+var CONFIG_PATH = path.join(
+  process.env["HOME"] ?? "~",
+  ".config",
+  "gtv",
+  "config.json"
+);
+var emptyStore = () => ({ version: 2, currentHost: null, devices: [] });
+var isLegacyConfig = (raw) => typeof raw === "object" && raw !== null && "host" in raw && !("devices" in raw);
+var readStore = () => {
+  if (!fs.existsSync(CONFIG_PATH)) return emptyStore();
+  const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  if (isLegacyConfig(raw)) {
+    return { version: 2, currentHost: raw.host, devices: [raw] };
+  }
+  const store = raw;
+  const devices = store.devices ?? [];
+  return {
+    version: 2,
+    currentHost: store.currentHost ?? devices[0]?.host ?? null,
+    devices,
+    ...store.preferences ? { preferences: store.preferences } : {}
+  };
+};
+var writeStore = (store) => {
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(store, null, 2) + "\n");
+};
+var listDevices = () => readStore().devices;
+var getCurrentDevice = () => {
+  const store = readStore();
+  return store.devices.find((device) => device.host === store.currentHost) ?? store.devices[0] ?? null;
+};
+var findDevice = (query) => {
+  const needle = query.toLowerCase();
+  return listDevices().find(
+    (device) => device.host === query || device.name?.toLowerCase() === needle
+  ) ?? null;
+};
+var upsertDevice = (device, { makeCurrent = true } = {}) => {
+  const store = readStore();
+  const existing = store.devices.find((d) => d.host === device.host);
+  const merged = existing ? { ...existing, ...device, cert: device.cert ?? existing.cert } : device;
+  const devices = existing ? store.devices.map((d) => d.host === device.host ? merged : d) : [...store.devices, merged];
+  writeStore({
+    ...store,
+    currentHost: makeCurrent ? device.host : store.currentHost ?? device.host,
+    devices
+  });
+};
+var setCurrentDevice = (host) => {
+  const store = readStore();
+  if (!store.devices.some((device) => device.host === host)) return false;
+  writeStore({ ...store, currentHost: host });
+  return true;
+};
+var deleteConfig = () => {
+  if (!fs.existsSync(CONFIG_PATH)) return false;
+  fs.unlinkSync(CONFIG_PATH);
+  return true;
+};
+var removeDevices = (hosts) => {
+  const store = readStore();
+  const devices = store.devices.filter((device) => !hosts.includes(device.host));
+  if (devices.length === 0) {
+    deleteConfig();
+    return;
+  }
+  const currentHost = devices.some(
+    (device) => device.host === store.currentHost
+  ) ? store.currentHost : devices[0].host;
+  writeStore({ ...store, currentHost, devices });
+};
+var readPreferences = () => readStore().preferences ?? {};
+var writePreferences = (partial) => {
+  const store = readStore();
+  const preferences = { ...store.preferences, ...partial };
+  writeStore({ ...store, preferences });
+  return preferences;
+};
+var readConfig = () => getCurrentDevice();
+
+// src/keycodes.ts
+import { RemoteKeyCode } from "@kud/androidtv-remote";
+var KEYS = {
+  home: RemoteKeyCode.KEYCODE_HOME,
+  back: RemoteKeyCode.KEYCODE_BACK,
+  power: RemoteKeyCode.KEYCODE_POWER,
+  up: RemoteKeyCode.KEYCODE_DPAD_UP,
+  down: RemoteKeyCode.KEYCODE_DPAD_DOWN,
+  left: RemoteKeyCode.KEYCODE_DPAD_LEFT,
+  right: RemoteKeyCode.KEYCODE_DPAD_RIGHT,
+  select: RemoteKeyCode.KEYCODE_DPAD_CENTER,
+  play: RemoteKeyCode.KEYCODE_MEDIA_PLAY_PAUSE,
+  stop: RemoteKeyCode.KEYCODE_MEDIA_STOP,
+  next: RemoteKeyCode.KEYCODE_MEDIA_NEXT,
+  prev: RemoteKeyCode.KEYCODE_MEDIA_PREVIOUS,
+  fwd: RemoteKeyCode.KEYCODE_MEDIA_FAST_FORWARD,
+  rwd: RemoteKeyCode.KEYCODE_MEDIA_REWIND,
+  "vol-up": RemoteKeyCode.KEYCODE_VOLUME_UP,
+  "vol-down": RemoteKeyCode.KEYCODE_VOLUME_DOWN,
+  mute: RemoteKeyCode.KEYCODE_VOLUME_MUTE,
+  menu: RemoteKeyCode.KEYCODE_MENU,
+  search: RemoteKeyCode.KEYCODE_SEARCH,
+  sleep: RemoteKeyCode.KEYCODE_SLEEP,
+  wakeup: RemoteKeyCode.KEYCODE_WAKEUP,
+  input: RemoteKeyCode.KEYCODE_TV_INPUT,
+  enter: RemoteKeyCode.KEYCODE_ENTER,
+  "channel-up": RemoteKeyCode.KEYCODE_CHANNEL_UP,
+  "channel-down": RemoteKeyCode.KEYCODE_CHANNEL_DOWN,
+  info: RemoteKeyCode.KEYCODE_INFO,
+  guide: RemoteKeyCode.KEYCODE_GUIDE,
+  settings: RemoteKeyCode.KEYCODE_SETTINGS
+};
+var KEY_LABELS = {
+  home: "Home",
+  back: "Back",
+  power: "Power",
+  up: "\u25B2",
+  down: "\u25BC",
+  left: "\u25C4",
+  right: "\u25BA",
+  select: "OK",
+  play: "\u23EF",
+  stop: "\u23F9",
+  next: "\u23ED",
+  prev: "\u23EE",
+  fwd: "\u23E9",
+  rwd: "\u23EA",
+  "vol-up": "Vol+",
+  "vol-down": "Vol-",
+  mute: "Mute",
+  menu: "Menu",
+  search: "Search"
+};
+
+// src/client.ts
+import { createAndroidRemote } from "@kud/androidtv-remote";
+var CONNECT_TIMEOUT_MS = 8e3;
+var connect = () => {
+  const config = readConfig();
+  if (!config) throw new Error("No TV configured. Run `gtv pair` first.");
+  const remote = createAndroidRemote(config.host, {
+    pairing_port: 6467,
+    remote_port: config.port ?? 6466,
+    service_name: config.name ?? "gtv",
+    ...config.cert ? { cert: config.cert } : {}
+  });
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      remote.stop();
+      reject(
+        new Error(
+          `Timed out connecting to ${config.host}. Run \`gtv pair\` again if the TV is online.`
+        )
+      );
+    }, CONNECT_TIMEOUT_MS);
+    const fail = (error) => {
+      clearTimeout(timeout);
+      remote.stop();
+      reject(error);
+    };
+    remote.once("ready", () => {
+      clearTimeout(timeout);
+      resolve(remote);
+    });
+    remote.once(
+      "unpaired",
+      () => fail(new Error("TV rejected the saved pairing. Run `gtv pair` again."))
+    );
+    remote.once("error", fail);
+    remote.start().then((started) => {
+      if (!started)
+        fail(
+          new Error(
+            `Could not connect to ${config.host}. Check that remote control is enabled on the TV.`
+          )
+        );
+    }).catch(fail);
+  });
+};
+var withRemote = async (fn) => {
+  const remote = await connect();
+  try {
+    fn(remote);
+    await new Promise((r) => setTimeout(r, 300));
+  } finally {
+    remote.stop();
+  }
+};
+var sendKey = (keyCode) => withRemote((remote) => remote.sendKey(keyCode));
+var launchApp = (deeplink) => withRemote((remote) => remote.sendAppLink(deeplink));
+
+// src/session.ts
+import EventEmitter from "events";
+import { createAndroidRemote as createAndroidRemote2 } from "@kud/androidtv-remote";
+var createSession = (device) => {
+  const emitter = new EventEmitter();
+  const state = {
+    tvName: null,
+    host: null,
+    connected: false,
+    powered: null,
+    volume: null,
+    currentApp: null,
+    error: null
+  };
+  let ready = false;
+  let remote;
+  const update = (patch) => {
+    Object.assign(state, patch);
+    emitter.emit("change", state);
+  };
+  const config = device ?? getCurrentDevice();
+  if (!config) {
+    update({ error: "No TV configured. Run `gtv pair` first." });
+  } else {
+    update({ tvName: config.name ?? "Google TV", host: config.host });
+    remote = createAndroidRemote2(config.host, {
+      pairing_port: 6467,
+      remote_port: config.port ?? 6466,
+      service_name: config.name ?? "gtv",
+      ...config.cert ? { cert: config.cert } : {}
+    });
+    remote.on("ready", () => {
+      ready = true;
+      update({ connected: true, error: null });
+    });
+    remote.on("powered", (powered) => update({ powered }));
+    remote.on("volume", (volume) => update({ volume }));
+    remote.on("current_app", (currentApp) => update({ currentApp }));
+    remote.on("error", (error) => {
+      ready = false;
+      update({ connected: false, error: error.message });
+    });
+    remote.on("unpaired", () => {
+      ready = false;
+      update({
+        connected: false,
+        error: "TV rejected the saved pairing. Run `gtv pair` again."
+      });
+    });
+    remote.start().catch((error) => update({ error: error.message }));
+  }
+  const withReady = (fn) => {
+    if (!ready || !remote) return;
+    try {
+      fn(remote);
+    } catch (error) {
+      ready = false;
+      update({
+        connected: false,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  };
+  const sendKey2 = (keyCode, direction) => withReady((r) => r.sendKey(keyCode, direction));
+  const typeText = (text) => withReady((r) => r.sendText(text));
+  const launchApp2 = (link) => withReady((r) => r.sendAppLink(link));
+  const stop = () => remote?.stop();
+  return Object.assign(emitter, {
+    state,
+    sendKey: sendKey2,
+    typeText,
+    launchApp: launchApp2,
+    stop
+  });
+};
+
+// src/discovery.ts
+import { spawn } from "child_process";
+import dns from "dns/promises";
+var browseServices = (timeout) => new Promise((resolve) => {
+  const names = [];
+  const proc = spawn("dns-sd", ["-B", "_androidtvremote2._tcp", "local"]);
+  proc.stdout.on("data", (data) => {
+    for (const line of data.toString().split("\n")) {
+      const match = line.match(
+        /Add\s+\d+\s+\d+\s+\S+\s+_androidtvremote2\._tcp\.\s+(.+)$/
+      );
+      if (match) names.push(match[1].trim());
+    }
+  });
+  setTimeout(() => {
+    proc.kill();
+    resolve([...new Set(names)]);
+  }, timeout);
+});
+var resolveService = (name) => new Promise((resolve) => {
+  const proc = spawn("dns-sd", [
+    "-L",
+    name,
+    "_androidtvremote2._tcp",
+    "local"
+  ]);
+  let output = "";
+  proc.stdout.on("data", (data) => {
+    output += data.toString();
+    const match = output.match(/can be reached at ([^:]+):(\d+)/);
+    if (match) {
+      proc.kill();
+      resolve({ hostname: match[1], port: parseInt(match[2], 10) });
+    }
+  });
+  setTimeout(() => {
+    proc.kill();
+    resolve(null);
+  }, 3e3);
+});
+var discover = async (opts = {}) => {
+  const timeout = opts.timeout ?? 5e3;
+  const names = await browseServices(timeout);
+  if (names.length === 0) return [];
+  const resolved = await Promise.all(
+    names.map(async (name) => {
+      const service = await resolveService(name);
+      if (!service) return null;
+      const { address } = await dns.lookup(service.hostname, { family: 4 });
+      return {
+        name,
+        host: address,
+        hostname: service.hostname,
+        port: service.port
+      };
+    })
+  );
+  return resolved.filter((d) => d !== null);
+};
+
+// src/pairing.ts
+import { createAndroidRemote as createAndroidRemote3 } from "@kud/androidtv-remote";
+var pair = (opts) => new Promise((resolve, reject) => {
+  const onStatus = opts.onStatus ?? (() => {
+  });
+  onStatus("connecting");
+  const remote = createAndroidRemote3(opts.hostname ?? opts.host, {
+    pairing_port: 6467,
+    service_name: opts.serviceName ?? "gtv"
+  });
+  const fail = (message) => {
+    remote.stop();
+    reject(new Error(message));
+  };
+  remote.on("secret", async () => {
+    onStatus("awaiting-pin");
+    try {
+      const pin = await opts.onSecret();
+      onStatus("pairing");
+      remote.sendCode(pin);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  });
+  remote.on("ready", () => {
+    const cert = remote.getCertificate();
+    const device = {
+      host: opts.host,
+      port: opts.port,
+      name: opts.name ?? opts.serviceName ?? "gtv",
+      cert
+    };
+    if (opts.save !== false) upsertDevice(device);
+    onStatus("paired");
+    remote.stop();
+    resolve({ cert, device });
+  });
+  remote.on("unpaired", () => fail("TV rejected the pairing request."));
+  remote.on("error", (error) => fail(error.message));
+  remote.start().then((paired) => {
+    if (!paired)
+      fail(
+        "Could not connect to TV. Check that 'Remote Device Settings \u2192 Control remotely' is enabled."
+      );
+  }).catch((error) => fail(error.message));
+});
+
+// src/apps.ts
+var APPS = [
+  { id: "netflix", name: "Netflix", packageName: "com.netflix.ninja" },
+  {
+    id: "youtube",
+    name: "YouTube",
+    packageName: "com.google.android.youtube.tv"
+  },
+  {
+    id: "primevideo",
+    name: "Prime Video",
+    packageName: "com.amazon.amazonvideo.livingroom"
+  },
+  { id: "plex", name: "Plex", packageName: "com.plexapp.android" },
+  { id: "putio", name: "Put.io", packageName: "io.put.putio" },
+  { id: "arte", name: "Arte", packageName: "tv.arte.plus7" },
+  { id: "disney", name: "Disney+", packageName: "com.disney.disneyplus" },
+  { id: "spotify", name: "Spotify", packageName: "com.spotify.tv.android" },
+  { id: "twitch", name: "Twitch", packageName: "tv.twitch.android.app" },
+  { id: "max", name: "Max", packageName: "com.wbd.stream" }
+];
+var appLink = (app) => app.link ?? `market://launch?id=${app.packageName}`;
+var findApp = (query) => {
+  const q = query.trim().toLowerCase();
+  return APPS.find((app) => app.id === q || app.name.toLowerCase() === q);
+};
+var listApps = () => APPS;
+export {
+  APPS,
+  CONFIG_PATH,
+  KEYS,
+  KEY_LABELS,
+  RemoteDirection,
+  RemoteKeyCode2 as RemoteKeyCode,
+  appLink,
+  connect,
+  createSession,
+  deleteConfig,
+  discover,
+  findApp,
+  findDevice,
+  getCurrentDevice,
+  launchApp,
+  listApps,
+  listDevices,
+  pair,
+  readConfig,
+  readPreferences,
+  readStore,
+  removeDevices,
+  sendKey,
+  setCurrentDevice,
+  setDebug,
+  upsertDevice,
+  withRemote,
+  writePreferences
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kud/gtv",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Google TV control library — device store, discovery, pairing, and a stateful remote session",
+  "keywords": [
+    "google-tv",
+    "android-tv",
+    "remote-control",
+    "androidtvremote2"
+  ],
+  "license": "MIT",
+  "author": "Erwann Mest <m@kud.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kud/gtv.git"
+  },
+  "homepage": "https://github.com/kud/gtv#readme",
+  "bugs": {
+    "url": "https://github.com/kud/gtv/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@kud/androidtv-remote": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}