Govee API Client

A TypeScript client for the Govee Developer API. Control your Govee lights, appliances, and other smart devices from code.

Install

npm install @felixgeelhaar/govee-api-client

Getting Started

You'll need a Govee API key. Get one from the Govee Developer Platform.

import { GoveeClient, ColorRgb, Brightness } from '@felixgeelhaar/govee-api-client';

const client = new GoveeClient({ apiKey: 'your-api-key' });

// List your devices
const devices = await client.getDevices();

// Find and control a light
const light = await client.findDeviceByName('Living Room');

if (light) {
  await client.turnOn(light.deviceId, light.model);
  await client.setBrightness(light.deviceId, light.model, new Brightness(75));
  await client.setColor(light.deviceId, light.model, new ColorRgb(255, 120, 50));
}

You can also set the GOVEE_API_KEY environment variable and skip passing it to the constructor:

const client = new GoveeClient(); // reads from GOVEE_API_KEY

What You Can Do

Basic Controls

await client.turnOn(deviceId, model);
await client.turnOff(deviceId, model);
await client.setBrightness(deviceId, model, new Brightness(75));

Colors

import { ColorRgb, ColorTemperature } from '@felixgeelhaar/govee-api-client';

// Set an RGB color
await client.setColor(deviceId, model, new ColorRgb(255, 0, 0));

// Set a color temperature
await client.setColorTemperature(deviceId, model, ColorTemperature.warmWhite());

// Turn on with color and brightness in one call
await client.turnOnWithColor(deviceId, model, new ColorRgb(0, 255, 0), new Brightness(80));

Scenes

import { LightScene } from '@felixgeelhaar/govee-api-client';

// Browse available scenes for a device
const scenes = await client.getDynamicScenes(deviceId, model);

// Apply a built-in scene
await client.setLightScene(deviceId, model, LightScene.sunset());
await client.setLightScene(deviceId, model, LightScene.aurora());

Segments (for LED strips and curtain lights)

import { SegmentColor, ColorRgb } from '@felixgeelhaar/govee-api-client';

await client.setSegmentColors(deviceId, model, [
  new SegmentColor(0, new ColorRgb(255, 0, 0)),
  new SegmentColor(1, new ColorRgb(0, 255, 0)),
  new SegmentColor(2, new ColorRgb(0, 0, 255)),
]);

Music Mode

import { MusicMode } from '@felixgeelhaar/govee-api-client';

await client.setMusicMode(deviceId, model, new MusicMode(1, 75));

Toggles

await client.setNightlightToggle(deviceId, model, true);
await client.setGradientToggle(deviceId, model, true);
await client.setSceneStageToggle(deviceId, model, true);

Device State

const state = await client.getDeviceState(deviceId, model);

console.log(state.getPowerState());    // true / false
console.log(state.isOnline());         // true / false
console.log(state.getBrightness());    // 0-100

Configuration

const client = new GoveeClient({
  apiKey: 'your-api-key',
  timeout: 30000,           // request timeout in ms (default: 30000)
  rateLimit: 95,            // requests per minute (default: 95)
  enableRetries: true,      // retry failed requests (default: false)
  retryPolicy: 'production', // 'development', 'testing', or 'production'
});

Rate Limiting

The client automatically stays within Govee's API rate limits (100 requests/min). By default it allows 95 requests/min, leaving a small buffer.

Retries

When enabled, failed requests are retried with exponential backoff. The built-in presets handle common scenarios:

• production — 3 attempts, circuit breaker enabled
• development — 5 attempts, circuit breaker disabled
• testing — 2 attempts, conservative settings

You can also pass a custom RetryPolicy instance for full control. See the examples for details.

Error Handling

import {
  GoveeApiError,
  InvalidApiKeyError,
  RateLimitError,
  NetworkError,
} from '@felixgeelhaar/govee-api-client';

try {
  await client.turnOn(deviceId, model);
} catch (error) {
  if (error instanceof InvalidApiKeyError) {
    console.log('Check your API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Too many requests. Retry in ${error.getRetryAfterMs()}ms`);
  } else if (error instanceof NetworkError) {
    console.log('Network issue — retryable:', error.isRetryable());
  } else if (error instanceof GoveeApiError) {
    console.log('API error:', error.message);
  }
}

Requirements

• Node.js 20 or higher
• A Govee Developer API key

Development

npm install
npm run build
npm test
npm run test:coverage

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT