integrations/readme.md

# @smarthome.exchange/integrations

🔌 TypeScript-native device integrations for smarthome.exchange.

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/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

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

```bash
pnpm add @smarthome.exchange/integrations
```

## Use The Default Registry

```ts
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

```ts
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

```bash
pnpm cli list
pnpm cli inspect hue
pnpm cli discover
pnpm cli setup hue
```

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

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

## Regenerating Home Assistant Port Skeletons

```bash
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

```bash
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](./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.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.