hovee

A type-safe, high-performance TypeScript client for the Govee Developer API (v1).

If you need you can check the documentation here: https://developer.govee.com/reference/get-you-devices

Features

• 🛡️ Strong Type Safety: Full TypeScript definitions for all devices, capabilities, and events.
• 🚀 Modern Stack: Built with ky for optimized HTTP requests and native retry support.
• 📡 Real-time Events: Integrated MQTT support for listening to device state changes.
• 🎮 Granular Control: Comprehensive support for controlling brightness, color, modes, and scenes.
• 📦 Dual Support: ESM and CommonJS support for modern and legacy projects.

Installation

npm install hovee

Quick Start

import { GoveeClient } from 'hovee';

// Initialize the client
const client = new GoveeClient({
  apiKey: 'YOUR_GOVEE_API_KEY',
});

// Discover your devices
const devices = await client.getDevices();
console.log(`Found ${devices.length} devices`);

// Turn on the first device
const device = devices[0];
await client.controlDevice(device.sku, device.device, {
  type: 'devices.capabilities.on_off',
  instance: 'powerSwitch',
  value: 1,
});

API Documentation

GoveeClient

The main entry point for interacting with the Govee API.

new GoveeClient(config: GoveeClientConfig)

Creates a new client instance.

• apiKey: Your Govee Developer API Key.

getDevices(): Promise<GoveeDevice[]>

Fetches all devices associated with your account and their supported capabilities.

getDeviceState(sku: string, device: string): Promise<DeviceStatePayload>

Queries the current status (power, brightness, color, etc.) of a specific device.

controlDevice(sku: string, device: string, capability: ControlCapability): Promise<ControlDeviceResponse>

Sends a control command to a device.

• Common Capabilities:
  • powerSwitch: value: 0 | 1
  • brightness: value: number (0-100)
  • colorRgb: value: number (Integer representation of RGB)
  • colorTemperatureK: value: number (Kelvin)

getScenes(sku: string, device: string): Promise<ScenePayload>

Fetches available dynamic light scenes for a device.

getDIYScenes(sku: string, device: string): Promise<ScenePayload>

Fetches user-created DIY scenes for a device.

Real-Time Events (MQTT)

If your device supports the devices.capabilities.event capability, you can listen for real-time state changes via MQTT.

import { createEventSubscription } from 'hovee';

const subscription = createEventSubscription('YOUR_API_KEY');

subscription.on('connected', () => {
  console.log('Connected to Govee MQTT');
});

subscription.on('message', (event) => {
  console.log('State changed:', event.sku, event.device);
  event.capabilities.forEach((cap) => {
    console.log(`- ${cap.instance}: ${cap.state.value}`);
  });
});

subscription.on('error', (err) => {
  console.error('MQTT Error:', err);
});

subscription.connect();

// Later:
// subscription.disconnect();

Advanced: Type Safety

Hovee uses discriminated unions and mapped types to ensure that your control commands are valid at compile time.

import { ControlCapability } from 'hovee';

// Valid control command
const turnOn: ControlCapability = {
  type: 'devices.capabilities.on_off',
  instance: 'powerSwitch',
  value: 1,
};

// Valid brightness command
const dim: ControlCapability = {
  type: 'devices.capabilities.range',
  instance: 'brightness',
  value: 50,
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © [Your Name]