# @homebridge/hap-client

> A client for HAP-NodeJS.

Latest version **5.4.0** (published 2026-10-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install @homebridge/hap-client
pnpm add @homebridge/hap-client
yarn add @homebridge/hap-client
bun add @homebridge/hap-client
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.4.0 |
| Published | 2026-10-31 |
| First published | 2024-03-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 291.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 7 |
| Author | Homebridge |
| Maintainers | oznu, northernman, supereg, khaost, ebaauw, dustin.greif, nfarina, bwp91 |
| Keywords | hap, homebridge, api |

## Links

- npm: https://www.npmjs.com/package/@homebridge/hap-client
- Repository: https://github.com/homebridge/hap-client
- Homepage: https://github.com/homebridge/hap-client/blob/latest#readme
- Issues: https://github.com/homebridge/hap-client/issues/
- npm.io page: https://npm.io/package/@homebridge/hap-client

## Dependencies (3)

- [decamelize](https://npm.io/package/decamelize.md) ^7.0.0
- [inflection](https://npm.io/package/inflection.md) ^3.0.2
- [bonjour-service](https://npm.io/package/bonjour-service.md) ^1.4.4

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 5.4.0 (latest) — 2026-10-31
- 5.4.1-beta.3 (beta) — 2026-11-21
- 5.4.1-beta.2 — 2026-11-16
- 5.4.1-beta.1 — 2026-11-16
- 5.4.1-beta.0 — 2026-11-14
- 5.40.1-beta.0 — 2026-11-14
- 5.4.0-beta.13 — 2026-10-31
- 5.4.0-beta.12 — 2026-10-31
- 5.4.0-beta.11 — 2026-10-31
- 5.4.0-beta.10 — 2026-10-31
- 5.4.0-beta.9 — 2026-10-31
- 5.4.0-beta.8 — 2026-10-31
- 5.4.0-beta.7 — 2026-10-28
- 5.4.0-beta.6 — 2026-10-25
- 5.4.0-beta.5 — 2026-10-25
- … 146 more at https://npm.io/package/@homebridge/hap-client/versions

## README

<p align="center">
  <a href="https://homebridge.io"><img src="https://raw.githubusercontent.com/homebridge/branding/latest/logos/homebridge-color-round-stylized.png" alt="Homebridge Logo" height="140"></a>
</p>
<span align="center">

# HAP Client

[![npm](https://shields.io/npm/v/@homebridge/hap-client/latest)](https://www.npmjs.com/package/@homebridge/hap-client)
[![npm](https://shields.io/npm/dt/@homebridge/hap-client?label=downloads)](https://www.npmjs.com/package/@homebridge/hap-client)<br>
[![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=hb-discord)](https://discord.com/channels/432663330281226270/742733745743855627)

</span>

A client for an insecure HAP-NodeJS instance. Provides a Typescript based interface based on the homekit accessory protocol, allowing the creation of clients able to connect to and control Homebridge devices.

## API

```
const { HapClient } = require('@homebridge/hap-client');

this.hapClient = new HapClient({
  config: { debug: true },
  pin: config.username,
  logger: this.log,
});

this.monitor = await this.hapClient.monitorCharacteristics(services?: ServiceType[]);  // Creates event monitors for all event capabable Homebridge services.  If a list of services is, this list is used rather than all
```

The discovery timeout can be configured by setting the `discoveryTimeout` property in the `config` object.

Set `debugRawPackets: true` together with `debug: true` to pass complete HAP event-monitor TCP packets and full `getValue()` HTTP exchanges to the logger's `debug` method as plain text. A `getValue()` exchange includes the serialized GET request followed by the response status line, headers, and unparsed body. Raw sent packets can contain the bridge PIN, so only enable this temporarily and treat the resulting logs as sensitive.

```
const { HapClient } = require('@homebridge/hap-client');

this.hapClient = new HapClient({
  config: { debug: true, discoveryTimeout: 5000, instanceBlacklist: ['34:42:4E:4A:38:00', '6E:69:51:34:54:00']},
  pin: config.username,
  logger: this.log,
});

// the discovery process will auto-start now with the timeout of 5 seconds
```

It's possible to control the discovery process manually, by settings the `autoStartDiscovery` property to `false` and then calling `this.hapClient.startDiscovery(discoveryTimeout?: number)` when ready. If no timeout is provided to the function, the `discoveryTimeout` property will be used from the `config` object, and if that is not provided either, the default discovery timeout (60 seconds) will be used.
It's also possible to stop the discovery process manually by calling `stopDiscovery()`

```
const { HapClient } = require('@homebridge/hap-client');

this.hapClient = new HapClient({
  config: { debug: true, autoStartDiscovery: false, discoveryTimeout: 10000 },
  pin: config.username,
  logger: this.log,
});

this.hapClient.startDiscovery(); // use the timeout provided in the config, 10000 ms
this.hapClient.startDiscovery(5000); // use the argument as timeout, 5000 ms

this.hapClient.stopDiscovery(); // stop the discovery process manually
```

## hap-client Events

```
this.hapClient.on('instance-discovered', this.instanceDiscovered(instance: HapInstance));  // Emitted during discovery for each HB instance discovered

this.hapClient.on('instance-configuration-changed', this.instanceChanged(instance: HapInstance));  // Emitted during discovery for each HB instance change

this.hapClient.on('discovery-terminated', this.discoveryTerminated());  // Instance discovery was terminated

this.hapClient.on('discovery-ended', this.discoveryEnded());  // Emitted when discovery has ended ( 60 Seconds )

this.hapClient.on('discovery-stopped', this.discoveryStopped());  // Emitted when discovery has been stopped manually

this.monitor.on('service-update', this.serviceUpdate(services)); // Emitted when a characteristic change is received from a homebridge service

this.monitor.on('monitor-close', this.monitorClose(instance, hadError)); // Emitted when the connection to a homebridge service is closed ( likely a restart )

this.monitor.on('monitor-error', this.monitorError(instance, error)); // Emitted when the connection to a homebridge service has an error ( likely a restart )

this.monitor.on('monitor-refresh', this.monitorRefresh(instance, error)); // Emitted when the connection to a homebridge instance has been refreshed or restarted
```

When a monitored service reports a `StatusActive` change, the monitor refreshes its other readable, event-enabled characteristics before emitting `service-update`. This ensures any HAP error statuses returned during an availability change are reflected in the emitted service.

## Dependent Applications

- homebridge-config-ui-x
- homebridge-gsh
- node-red-contrib-homebridge-automation

- [NPM Dependents](https://www.npmjs.com/package/@homebridge/hap-client?activeTab=dependents)

## Credits

- HAP Client was originally created by [oznu](https://github.com/oznu).

---
_Source: https://npm.io/package/@homebridge/hap-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
