homey-features

Shared feature registry and Base64url bitmap helpers for Homey. Zero dependencies, no build step, and no targeting, storage or network access. Requires Node 18 or later; the implementation also works in browser and React Native bundles without Node-specific APIs or polyfills.

Usage

const { encode, fromKeys, hasFeature, parseHeaders } = require('homey-features');

const features = encode(fromKeys(['test.basic', 'test.compatibility']));
// features === 'BQ'

const bytes = parseHeaders(response.headers);
if (hasFeature(bytes, 'test.basic')) {
  // Use the feature advertised by the selected Homey.
}

Named ESM imports use the same implementation:

import { decode, hasFeature } from 'homey-features';

hasFeature(decode('AQ'), 'test.basic'); // true

fromKeys rejects unknown names; hasFeature returns false for them. decode rejects malformed or noncanonical values. parseHeaders accepts a Headers-like object with get(name) and returns an empty bitmap for missing or invalid values. merge(rollout, released) combines two byte arrays using bitwise OR so firmware can keep released features enabled independently of rollout values.

Permanent assignments

The array index in registry.json is the feature's bit number:

• Bits 0–3: test.basic, test.rollout, test.compatibility, test.released.
• Bits 4–15: reserved for future tests (null).
• Bits 16–8191: append-only production assignments.

Test names have no special behaviour and do not enable themselves. Never reorder the registry or reuse a production bit. Keep assigned names for older clients, even after rollout completes. Publish new assignments before configuring them.

Ping header

Homey advertises the bitmap on its existing /ping response:

X-Homey-Features: BQ

Bit n uses byte Math.floor(n / 8) and mask 1 << (n % 8). Values use Base64url without padding or trailing zero bytes. AA means all off, AQ enables bit 0, and BQ enables bits 0 and 2. The maximum is 1,024 bytes (8,192 bits), encoded as at most 1,366 characters. There is no version or revision header.

Flags signal availability, not authorization or entitlement.

Development

Run npm test for the four protocol tests. After npm ci --ignore-scripts, run npm run check to also verify the packed contents, credential-free installation, CommonJS/ESM imports and declarations. TypeScript is a development dependency only. npm run check:registry compares assignments with the latest published registry (or the initial beta); network errors fail the check, not skip it.

Releases

The intended repository and npm package are both public. Consumers need no private registry credentials. Package contents are GPL-3.0-only; see LICENSE.

Use develop for reviewed changes and production for releases. Bump the manifest and lockfile on develop with npm version minor --no-git-tag-version for new assignments, or patch for compatible fixes. A major version never permits bit reuse. Open a reviewed promotion to production; its workflow rechecks and publishes the verified artifact to npm latest. Afterwards, tag the published production commit vX.Y.Z and create short release notes.

Manual dispatch of the publication workflow is dry-run only. An already published version with identical contents is skipped; different contents fail. The workflow does not change versions, commit files or update consumers.

One-time setup, only after publication approval:

1. Create public athombv/node-homey-features, default branch develop. Protect develop and production with review and required Test checks.
2. An Athom npm maintainer publishes the verified package as 1.0.0-beta.0 with --tag beta, using interactive authentication and 2FA. Keep this one-time beta version change off develop; do not publish an empty placeholder.
3. Configure npm trusted publishing for organization athombv, repository node-homey-features, workflow publish-package-npm.yml, no environment, with npm publish allowed. No npm publishing token belongs in GitHub secrets.
4. Promote stable 1.0.0 to production. Complete the first OIDC publish within two days of configuring trust, or recreate the expired configuration.
5. Update consumers to published versions and regenerate their normal lockfiles.

Publishing uses GitHub-hosted runners, Node 24 and npm >=11.5.1. Public source and package enable automatic provenance with OIDC. See npm trusted publishing.

Before publication, test local tarballs in disposable workspaces. Do not commit file-path dependencies or fabricated registry lock entries. Final consumer lockfiles and clean registry installs require the published versions.