API Reference¶

Complete reference for all public exports from the ts-home-automation package. Organised by module.

import { createEngine, Automation, type Trigger, type TriggerContext } from "ts-home-automation";

Engine¶

createEngine(options)¶

Factory function that wires all core services together and returns an Engine object.

function createEngine(options: EngineOptions): Engine

EngineOptions¶

deviceRegistry sub-options:

services sub-options:

ServiceFactory<T>¶

type ServiceFactory<T> = (http: HttpClient, logger: Logger) => T;

A factory function that receives the engine's shared HTTP client and a scoped logger, and returns a service instance.

HomekitServiceFactory¶

type HomekitServiceFactory = (
  http: HttpClient,
  logger: Logger,
  mqtt: MqttService,
  deviceRegistry: DeviceRegistry | null,
) => HomekitService;

Extended factory for the HomeKit bridge that also receives the MQTT service and device registry.

Engine¶

The object returned by createEngine().

Example:

import { createEngine } from "ts-home-automation";

const engine = createEngine({
  automationsDir: new URL("./automations", import.meta.url).pathname,
  config: { mqtt: { host: "192.168.1.10" } },
  state: { persist: true },
});

process.on("SIGINT", () => engine.stop().then(() => process.exit(0)));
await engine.start();

Automation¶

abstract class Automation¶

Base class for all automations. Subclasses must implement name, triggers, and execute().

import { Automation, type Trigger, type TriggerContext } from "ts-home-automation";

export default class MyAutomation extends Automation {
  readonly name = "my-automation";
  readonly triggers: Trigger[] = [/* ... */];
  async execute(context: TriggerContext): Promise<void> { /* ... */ }
}

Abstract members¶

Optional members¶

Protected fields (injected by the framework)¶

Protected methods¶

Lifecycle hooks¶

Override these for setup and teardown. Both have empty default implementations.

Trigger¶

A discriminated union defining when an automation fires. Seven types are supported:

MQTT trigger¶

{ type: "mqtt"; topic: string; filter?: (payload: Record<string, unknown>) => boolean }

Cron trigger¶

{ type: "cron"; expression: string }

State trigger¶

{ type: "state"; key: string; filter?: (newValue: unknown, oldValue: unknown) => boolean }

Webhook trigger¶

{ type: "webhook"; path: string; methods?: ("GET" | "POST" | "PUT" | "DELETE")[] }

Device state trigger¶

{ type: "device_state"; friendlyName: string; filter?: (state: Record<string, unknown>, device: ZigbeeDevice) => boolean }

Requires DEVICE_REGISTRY_ENABLED=true.

Device joined trigger¶

{ type: "device_joined"; friendlyName?: string }

Requires DEVICE_REGISTRY_ENABLED=true. Omit friendlyName to fire for any device.

Device left trigger¶

{ type: "device_left"; friendlyName?: string }

Requires DEVICE_REGISTRY_ENABLED=true. Omit friendlyName to fire for any device.

TriggerContext¶

A discriminated union matching each trigger type. Use context.type to narrow:

AutomationManager¶

Manages discovery, registration, and lifecycle of automations. Available as engine.manager.

MqttService¶

Manages the MQTT connection and multiplexes subscriptions across automations.

import type { MqttService, MqttMessageHandler } from "ts-home-automation";

MqttMessageHandler¶

type MqttMessageHandler = (topic: string, payload: Record<string, unknown>) => void | Promise<void>;

Properties¶

Methods¶

Subscription dispatch internals:

• Exact-match topics use Map lookup (O(1))
• Wildcard topics use pre-split pattern matching (linear scan)
• JSON payload is parsed lazily — only when at least one handler matches
• Each handler is called independently; errors in one handler do not affect others

HttpClient¶

General-purpose HTTP client with structured logging, timeouts, and retry support.

import type { HttpClient, HttpRequestOptions, HttpResponse } from "ts-home-automation";

HttpRequestOptions¶

HttpResponse<T>¶

Methods¶

Retry behaviour: On network errors or 5xx responses, retries use exponential backoff starting at 500ms, doubling each attempt, capped at 10s. 4xx responses are never retried.

URL sanitisation: Sensitive query parameters (appid, apikey, api_key, token, key, secret) are masked with *** in log output.

HttpServer¶

HTTP server for health probes, webhooks, debug API, and web UI.

WebhookHandler¶

type WebhookHandler = (context: {
  method: string;
  headers: Record<string, string>;
  query: Record<string, string>;
  body: unknown;
}) => Promise<void>;

Route structure¶

Authentication uses Authorization: Bearer <token> header or a session cookie. Set HTTP_TOKEN to enable; leave empty for no authentication.

StateManager¶

In-memory key-value store with typed access, change listeners, and optional file persistence.

import type { StateManager, StateManagerOptions, StateChangeHandler } from "ts-home-automation";

StateManagerOptions¶

StateChangeHandler<T>¶

type StateChangeHandler<T> = (key: string, newValue: T | undefined, oldValue: T | undefined) => void;

Methods¶

Equality check: set() compares the new value against the current value before firing listeners. Primitives use strict equality (===); objects use JSON.stringify comparison. If values are equal, no listeners fire.

Listener warning: A warning is logged when more than 10 listeners are registered for a single key, to help detect leaks.

CronScheduler¶

Wraps the cron package for scheduled job management. Internal to the engine — automations interact with it via cron triggers.

Timezone is read from the TZ environment variable.

ServiceRegistry¶

Type-safe key-value registry for optional services. Services implementing ServicePlugin receive lifecycle hooks.

import type { ServiceRegistry } from "ts-home-automation";

ServicePlugin¶

Interface for services that need lifecycle hooks and HTTP route registration. See Custom Service Plugins for a full guide.

import type { ServicePlugin, CoreContext } from "ts-home-automation";

CoreContext¶

ServicePlugin interface¶

LogBuffer¶

Ring buffer for in-memory log storage. Used by the debug API and web UI.

import type { LogBuffer, LogEntry, LogQuery } from "ts-home-automation";

LogEntry¶

interface LogEntry {
  level: number;    // pino numeric level (10=trace, 20=debug, 30=info, 40=warn, 50=error, 60=fatal)
  time: number;     // Unix timestamp in ms
  msg: string;      // Log message
  [key: string]: unknown;  // Additional fields (automation, service, err, etc.)
}

LogQuery¶

DeviceRegistry¶

Zigbee2MQTT device discovery and state tracking. Available as engine.deviceRegistry or this.deviceRegistry in automations. Returns null when DEVICE_REGISTRY_ENABLED is not true.

See Device Registry for the full feature guide.

Query methods¶

Event methods¶

Persistence options¶

interface DeviceRegistryPersistenceOptions {
  persist?: boolean;    // default: false
  filePath?: string;    // default: "./device-registry.json"
}

Device base classes¶

Abstract automation classes for common Zigbee remotes. See Device Base Classes for handler details.

Configuration¶

Config¶

The resolved configuration object. See Configuration for all environment variables.

import type { Config } from "ts-home-automation";

loadConfig(overrides?)¶

function loadConfig(overrides?: Partial<Config>): Config

Reads environment variables, applies Zod validation, merges with optional overrides. Exits the process with a formatted error on validation failure.

Type exports¶

All Zigbee2MQTT, Shelly, Nanoleaf, Weather, and Notification types are re-exported from the package. See Device Types for a complete catalogue.

// Zigbee types
import type { OccupancyPayload, ColorLightSetCommand, ZigbeeDevice } from "ts-home-automation";

// Shelly types
import type { ShellySwitchStatus, ShellyCoverStatus } from "ts-home-automation";
// Or from the subpath:
import type { ShellySwitchStatus } from "ts-home-automation/types/shelly";

// Weather types
import type { WeatherService, CurrentWeather, DailyForecast } from "ts-home-automation";

// Notification types
import type { NotificationService, NotificationOptions } from "ts-home-automation";

// Nanoleaf types
import type { NanoleafState, NanoleafDeviceInfo } from "ts-home-automation";

Subpath imports¶

The package provides subpath exports for each type category: