@enfinitos/sdk-smart-home

EnfinitOS reference SDK for the SMART_HOME substrate. Built Matter-first: every accessory is defined as a Matter device on the canonical wire, and platform-specific bridges (Alexa Smart Home v3, Google Home APIs, SmartThings, HomeKit) layer over the Matter cluster spec.

Architecture

                       ┌─────────────────────────────────────────┐
                       │   @enfinitos/sdk-renderer-core (TS)     │
                       │   resolve / grant / event-ingest        │
                       └─────────────────────────────────────────┘
                                          ▲
                                          │
                       ┌──────────────────┴──────────────────┐
                       │  smart-home ts-core (Matter-first)  │
                       │  SmartHomeClient + MatterCluster +  │
                       │  ConsentManager                     │
                       └──────────────────┬──────────────────┘
                                          │
              ┌──────────────┬────────────┼────────────┬─────────────┐
              │              │            │            │             │
          ┌────────┐   ┌────────────┐  ┌────────┐  ┌────────┐   ┌────────┐
          │ Alexa  │   │Google Home │  │SmartTh.│  │HomeKit │   │ Matter │
          │SmartHmV3│  │  APIs '26  │  │ + Mtr  │  │+Matter │   │Cluster │
          └────────┘   └────────────┘  └────────┘  └────────┘   └────────┘
              │              │            │            │             │
          Discovery,      Google Home   SmartThings    HAP +       Vendor-
          ReportState,    APIs (2024-   Hub v3+,       Matter      neutral
          StateReport     announced),   Matter-native  bridge      cluster
          (v3)            programmable  through Hub    (HomeKit    spec
                          actions       Connect        is shifting (XML +
                          surface       protocol       to Matter   docs)
                                                       in 2026)

The Matter cluster is the canonical accessory model. Every platform-specific bridge translates a Matter device shape into its own surface. This means a new ecosystem (e.g. SmartThings Hub v4 with native Matter Casting) can be added by writing a new bridge against the cluster spec without touching the rest of the SDK.

Getting started

TypeScript core (Matter-first)

import { SmartHomeClient, EnfinitOSMatterCluster } from "@enfinitos/sdk-smart-home";

const client = new SmartHomeClient({
  apiBaseUrl: "https://api.enfinitos.com",
  authToken: jwt,
  homeId: hashedHomeId,
});
await client.start();

// Register an accessory under EnfinitOS's vendor-specific Matter cluster.
await client.registerMatterAccessory({
  accessoryId: "kitchen-frame-01",
  device: {
    vendorId: EnfinitOSMatterCluster.VENDOR_ID,
    productId: 0x0001,
    deviceType: "smart-frame",
  },
  capabilities: ["render-image", "render-headline", "trigger-cta"],
});

// Request the next display directive (an asset to render on the frame).
const directive = await client.fetchDirective({
  accessoryId: "kitchen-frame-01",
  surfaceId: "frame-rotate",
});
if (directive?.kind === "render-image") {
  myFrame.show(directive.imageUrl);
  await client.reportRenderStarted(directive);
}

Alexa Smart Home v3 skill

import { handler } from "@enfinitos/sdk-smart-home/alexa-smart-home";

// AWS Lambda entry point. The SDK ships an out-of-the-box handler
// that wires the v3 directive shape (Discovery, ReportState,
// StateReport, control directives) to the EnfinitOS rights plane.
exports.handler = handler({
  apiBaseUrl: "https://api.enfinitos.com",
  authToken: process.env.ENFINITOS_TOKEN!,
  // The skill ID maps to a SmartHomeRoom in EnfinitOS.
  alexaSkillId: process.env.ALEXA_SKILL_ID!,
});

Google Home APIs 2026

import { EnfinitOSGoogleHome } from "@enfinitos/sdk-smart-home/google-home";

const gh = new EnfinitOSGoogleHome({
  apiBaseUrl: "https://api.enfinitos.com",
  authToken: jwt,
  googleProjectId: "acme-home-prod",
});
await gh.registerStructure({
  structureId: "home/abc123",
  rooms: ["kitchen", "living-room"],
});

SmartThings

import { EnfinitOSSmartThings } from "@enfinitos/sdk-smart-home/smartthings";

const st = new EnfinitOSSmartThings({
  apiBaseUrl: "https://api.enfinitos.com",
  authToken: jwt,
  smartThingsAccessToken: process.env.ST_TOKEN!,
});
await st.bindLocation("location-id");

HomeKit (Swift)

import EnfinitOSHomeKit

let bridge = EnfinitOSHomeKitBridge(
    apiBaseUrl: URL(string: "https://api.enfinitos.com")!,
    authToken: jwt,
    homeId: hashedHomeId,
)
try bridge.registerMatterAccessory(.kitchenFrame)
try await bridge.start()

2026 platform notes

Matter 1.4

• Matter 1.4 is the floor (Q4 2024 release). It introduces Multi-Admin v2 (granular per-admin scope), Enhanced Multi-Fabric (faster fabric joins), Battery-Powered Routers (Thread mesh density), and the Camera and Smart Speaker device types (which our cluster extends).
• EnfinitOS vendor ID is 0xFFF1 (the Matter SIG-reserved test-vendor range; production gets reassigned once we ship a CSA- certified accessory). The custom cluster ID is 0xFC01, in the manufacturer-extended-cluster band.
• The cluster XML lives in matter-cluster-spec/enfinitos-cluster.xml. This is the canonical contract — Alexa, Google, SmartThings, HomeKit bridges all translate it.

Alexa Smart Home v3

• Directive format v3 is the only supported shape. Discovery, ReportState, StateReport, plus control directives (TurnOn, TurnOff, AdjustBrightness, SetVolume, etc.).
• Account linking uses OAuth 2.0 with PKCE. Refresh tokens rotate per Amazon's 2024 hardening.
• Skill lambda runs on Node.js 20 (Lambda's 2026 default). The SDK targets that runtime.

Google Home APIs 2026

• Google Home APIs is the new programmable surface announced at I/O 2024 and GA in 2026. It supersedes the deprecated "Smart Home Actions" (which themselves were the successor to the original Local Home SDK).
• The previous Local Home SDK is end-of-life as of Jan 2026. We do not target it.
• Authentication is Google Cloud IAM via service accounts; the SDK uses the @google-cloud/local-auth flow for development.

SmartThings

• SmartThings SDK with native Matter since Hub v3 (May 2024). The SDK reads/writes both the SmartThings device-state surface AND the Matter cluster directly when the local hub supports it.
• REST-based Cloud Connector pattern for cloud-only devices.

HomeKit + Matter

• HomeKit's Matter alignment — Apple's HomeKit framework registers Matter devices as first-class HMAccessory subclasses since iOS 17. In 2026, new accessories should be registered through Matter, not HAP, because HAP-only devices won't participate in cross-ecosystem (Google/Amazon) discovery.
• HomeKit Accessory Protocol (HAP) still works for the Apple-only case, but the SDK's EnfinitOSHomeKitBridge defaults to Matter registration and only falls back to HAP when the accessory declines Matter onboarding (rare in 2026).

Consent

Smart-home contexts are opt-in critical. A smart frame in your kitchen showing a sponsored recipe ad needs the household head's explicit consent — Apple's HomeKit, Amazon's Skill flow, and Google Home's structure-permission flow all surface this. The SDK ships ConsentManager that:

• Records the consent record at registration time.
• Re-prompts on substantive change (new sponsor type, new accessory).
• Refuses to deliver directives without an active consent.

Endpoint surface

Test plan

• TS core + bridges: Vitest under */src/__tests__/.
• HomeKit: XCTest under homekit/Tests/.