Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,19 @@ jobs:
echo "version=$VERSION" >> $GITHUB_OUTPUT
echo "Published version: $VERSION"

- name: Add publish summary
run: |
{
echo "## Published HAP Client"
echo
echo "| Property | Value |"
echo "| --- | --- |"
echo '| Version | `v${{ steps.get-published-version.outputs.version }}` |'
echo '| Release type | `${{ needs.determine-release-type.outputs.release_type }}` |'
echo '| npm tag | `${{ needs.determine-release-type.outputs.npm_tag }}` |'
echo '| Package | [View on npm](https://www.npmjs.com/package/@homebridge/hap-client/v/${{ steps.get-published-version.outputs.version }}) |'
} >> "$GITHUB_STEP_SUMMARY"

pre-release:
needs: [determine-release-type, publish]
name: Create GitHub Pre-Release
Expand Down
75 changes: 0 additions & 75 deletions .npmignore

This file was deleted.

23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,29 @@

All notable changes to `@homebridge/hap-client` will be documented in this file. This project tries to adhere to [Semantic Versioning](http://semver.org/).

## v5.4.0 (2026-10-31)

### Breaking Changes

- Retired the usage of axios for making HTTP requests. Now uses fetch instead.
- `getCharacteristic()` and `refreshServiceCharacteristics()` now set `status` on each characteristic and throw a `HapCharacteristicError` (check `error.name`) when it is nonzero, leaving `value` at its last good reading. Before, they only logged the error, so a stale `value` looked current.

### Changed

- feat: `debugRawPackets` option (with `debug: true`) logs raw event-monitor packets and `getValue()` exchanges. They can contain the bridge PIN
- feat: when a service's `StatusActive` changes, refresh its other characteristics before emitting `service-update`
- fix: fix empty HAP characteristic write responses (#95) (@dnicolson)
- fix: remember a refused pin on the client, so an unregistered bridge is named once, not every cycle
- feat: take the list of our own bridges, so another homebridge's refused pin logs at debug, not warn
- fix: add a bridge that registers after the monitor started to it, so it gets live updates too
- chore: run the type generator with tsx instead of ts-node
- chore(deps): dependency updates
- chore: prepare v5.4.0 changelog and drop unused axios
- fix: restore 5.3.0 behaviour for getResource errors and failed monitor syncs
- ci: add a publish summary to the release workflow
- chore: publish only dist, README, LICENSE and CHANGELOG to npm
- fix: sort the files allowlist for lint, and stop emitting source maps

## v5.3.0 (2026-08-31)

### Changed
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ this.monitor = await this.hapClient.monitorCharacteristics(services?: ServiceTyp

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');

Expand Down Expand Up @@ -81,6 +83,8 @@ this.monitor.on('monitor-error', this.monitorError(instance, error)); // Emitted
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
Expand Down
5 changes: 4 additions & 1 deletion eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,10 @@ export default antfu(
'style/quote-props': ['error', 'consistent-as-needed'],
'test/no-only-tests': 'error',
'ts/consistent-type-imports': 'off',
'unused-imports/no-unused-vars': ['error', { caughtErrors: 'none' }],
'unused-imports/no-unused-vars': [
'error',
{ caughtErrors: 'none' },
],
},
typescript: true,
formatters: {
Expand Down
24 changes: 24 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Examples

Build the local package, then inspect and monitor the HomeKit accessory named `Backyard Tree`:

```sh
npm run build
HAP_PIN=031-45-154 node examples/backyard-tree.js
```

During development, use Nodemon to rebuild and restart the example whenever its source or the client source changes:

```sh
HAP_PIN=031-45-154 npm run exampleWatch
```

Homebridge must be running in insecure mode (`-I`). Replace the example PIN with your bridge PIN.

The example limits discovery to bridge `69:62:B7:AE:38:D4`. Once discovery ends, it calls `getValue()` for every readable, event-enabled characteristic before printing the accessory's services, then subscribes to its event-enabled characteristics. Debug output includes each full `getValue()` HTTP response and the complete sent and received event-monitor packets as plain text, which may contain the bridge PIN and other sensitive values.

To inspect a different accessory without editing the file, set `HAP_ACCESSORY`:

```sh
HAP_PIN=031-45-154 HAP_ACCESSORY='Front Porch' node examples/backyard-tree.js
```
97 changes: 97 additions & 0 deletions examples/backyard-tree.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
/* eslint-disable no-console -- This example intentionally writes discovery results to the terminal. */
import process from 'node:process'

// Build first with `npm run build`; this imports the local package output.
// eslint-disable-next-line antfu/no-import-dist
import { HapClient } from '../dist/index.js'

const accessoryName = process.env.HAP_ACCESSORY ?? 'Backyard Tree'
const pin = process.env.HAP_PIN

if (!pin) {
console.error('Set HAP_PIN to your Homebridge PIN. See examples/README.md for an invocation.')
process.exit(1)
}

const client = new HapClient({
pin,
logger: console,
config: {
autoStartDiscovery: false,
debug: true,
debugRawPackets: true,
discoveryTimeout: 5000,
instanceWhitelist: ['69:62:B7:AE:38:D4'],
Comment thread
NorthernMan54 marked this conversation as resolved.
Resolved
},
})

function shutDown(exitCode = 0) {
client.destroy()
process.exit(exitCode)
}

process.once('SIGINT', () => shutDown(130))
process.once('SIGTERM', () => shutDown(143))

client.on('instance-discovered', (instance) => {
console.log(`Found ${instance.name} (${instance.username}) at ${instance.ipAddress}:${instance.port}`)
})

client.once('discovery-ended', async () => {
try {
console.log(`Discovery has ended`)
const services = await client.getAllServices()
const accessoryServices = services.filter(service => service.accessoryInformation?.Name === accessoryName)

if (!accessoryServices.length) {
const names = [
...new Set(services.map(service => service.accessoryInformation?.Name).filter(Boolean)),
]
throw new Error(`Accessory ${JSON.stringify(accessoryName)} was not found. Discovered: ${names.join(', ') || 'none'}`)
}

// Values included in the accessories response may be stale. Prime each
// readable, event-enabled characteristic with its latest value before
// displaying and monitoring the returned service objects.
await Promise.all(accessoryServices.flatMap(service =>
service.serviceCharacteristics
.filter(characteristic => characteristic.ev && characteristic.canRead)
.map(async (characteristic) => {
try {
console.log(`Retrieving lastest value for ${characteristic.description} ${JSON.stringify(await characteristic.getValue(), null, 2)}`)
} catch (error) {
console.warn(`Could not refresh ${service.serviceName} / ${characteristic.type}:`, error)
}
}),
))

// A HAP accessory is returned as one ServiceType per service. Services with
// the same bridge username and aid belong to this single accessory.
console.dir(accessoryServices, { depth: null, colors: process.stdout.isTTY })

const eventServices = accessoryServices.filter(service => service.serviceCharacteristics.some(characteristic => characteristic.ev))
if (!eventServices.length) {
console.log(`\n${accessoryName} has no event-enabled characteristics, so there are no packets to monitor.`)
client.destroy()
return
}

const monitor = await client.monitorCharacteristics(eventServices)
monitor.on('service-update', (updatedServices) => {
console.log(`\n[${new Date().toISOString()}] ${accessoryName} update:`)
console.dir(updatedServices, { depth: null, colors: process.stdout.isTTY })
})
monitor.on('monitor-error', (instance, error) => {
console.error(`Monitor error for ${instance.username}:`, error)
})

console.log(`\nMonitoring ${JSON.stringify(accessoryName)}. Change its state to see updates; press Ctrl+C to stop.`)
} catch (error) {
console.error(error)
client.destroy()
process.exitCode = 1
}
})

console.log(`Discovering bridges for ${JSON.stringify(accessoryName)}...`)
client.startDiscovery()
13 changes: 13 additions & 0 deletions nodemon.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"watch": [
"src",
"examples/backyard-tree.js"
],
"ext": "ts,js,json",
"ignore": [
"dist/**",
"node_modules/**"
],
"exec": "npm run build && node examples/backyard-tree.js",
"signal": "SIGTERM"
}
Loading
Loading