This package owns discovery, configuration flows, vendor clients, mappers, events, normalized service calls, and generated integration descriptors. It keeps device-specific code out of the hub so a runtime can add, remove, publish, or mature integrations without rewriting the canonical home state model.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

Publishing is restricted to https://packages.foss.global/ through publishConfig.

pnpm add @smarthome.exchange/integrations

Use The Default Registry

import { DiscoveryEngine, createDefaultIntegrationRegistry } from '@smarthome.exchange/integrations';

const registry = createDefaultIntegrationRegistry();
const engine = new DiscoveryEngine(registry);

console.log(registry.get('hue')?.displayName);

const candidates = await engine.runActiveDiscovery({});
console.log(candidates);

Public Surface

Export group	What it gives you
Core classes	`BaseIntegration`, `DescriptorOnlyIntegration`, `DiscoveryDescriptor`, `DiscoveryEngine`, `IntegrationRegistry`, `IntegrationRuntimeManager`, `ConsoleLogger`, `JsonFileConfigStore`.
Core errors	`IntegrationError`, `DiscoveryError`, `AuthenticationError`, `DeviceCommunicationError`.
Core types	Discovery, config-flow, runtime, service-call, entity, logging, and integration status contracts.
Protocol namespaces	`mdns`, `ssdp`, `http`, `mqtt`, `bluetooth`, and `usb` descriptor helpers.
Registry helpers	`integrations` and `createDefaultIntegrationRegistry()`.
Generated metadata	`generatedHomeAssistantPortIntegrations`, `generatedHomeAssistantPortCount`, and `handwrittenHomeAssistantPortDomains`.
Handwritten modules	Hue and Wolf Smartset exports from `ts/integrations/index.ts`.

Integration Lifecycle

const integration = registry.get('hue');

if (!integration) {
  throw new Error('Hue integration not found');
}

const matches = await engine.validateCandidate({
  id: 'hue:bridge:office',
  source: 'manual',
  integrationDomain: 'hue',
  displayName: 'Office Hue Bridge',
  confidence: 0.9,
  metadata: {
    baseUrl: 'https://192.168.1.20',
  },
});

console.log(matches);

The hub uses the same primitives through discoverIntegrationCandidates() and setupIntegration(...), then upserts normalized devices into the canonical device registry.

Home Assistant Port Skeletons

The package includes generated native TypeScript port skeletons for upstream Home Assistant component domains under ts/integrations/<domain>. These are not Python wrappers and not a compatibility namespace. They are TypeScript classes that start as descriptor-only integrations and get replaced by handwritten clients, mappers, discovery, config-flow, and runtime code as each port matures.

Current generated metadata includes generatedHomeAssistantPortCount = 1394. Descriptor-only integrations intentionally throw from setup() until a real TypeScript runtime exists.

Handwritten Integrations

Integration	Current capability
Hue	Bridge discovery, validation, config flow, light/device/entity mapping, and `light.turn_on` / `light.turn_off` service calls.
Wolf Smartset	Discovery/config/runtime structure is present, currently marked `descriptor-only`.

The integrations array also registers many handwritten domain folders and then fills gaps from the generated Home Assistant descriptors when createDefaultIntegrationRegistry() runs.

CLI

pnpm cli list
pnpm cli inspect hue
pnpm cli discover
pnpm cli setup hue

When installed as a package, the binary is shx-integrations:

shx-integrations list
shx-integrations inspect hue
shx-integrations discover
shx-integrations setup hue

Regenerating Home Assistant Port Skeletons

pnpm generate:ha

The generator reads HA_CORE_COMPONENTS_DIR or /tmp/opencode/homeassistant-core/homeassistant/components, preserves handwritten integration folders, and regenerates only folders with the .generated-by-smarthome-exchange marker.

Boundaries

This package does not own canonical device registry state, approvals, audit receipts, automations, dashboards, or persistent home state. Those stay in @smarthome.exchange/hub. Integrations normalize vendor reality into shared interface contracts and expose runtime/service primitives for the hub to consume.

Scripts

pnpm cli list
pnpm generate:ha
pnpm test
pnpm build
pnpm buildDocs

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@smarthome.exchange/integrations