SDK at a glance

This page is the compact reference: one place to look up a signature, a default or a limit. It is maintained by hand next to the generated SDK reference; if the two ever disagree, the reference wins.

It does not teach. For when and why to use each member, and for what happens in which order, read the plugin guide (start with its lifecycle), Values and Testing. Each section below links to the matching part of the guide. To learn by building, follow the tutorial.

Imports: @lox-nexus/plugin-sdk (classes), @lox-nexus/plugin-sdk/values, @lox-nexus/plugin-sdk/testing, @lox-nexus/plugin-sdk/wire.

@lox-nexus/plugin-sdk

Plugin (reference)

abstract class Plugin<Config = unknown> extends Disposable {
  constructor(protected readonly context: PluginContext)
  get config(): Config
  get log(): PluginLogger
  get logLevel(): PluginLogLevel                           // { current, onChange(listener) }
  get store(): PluginStore
  get status(): PluginStatus
  get http(): PluginHttp
  get slug(): string | undefined
  get timeZone(): string                                   // IANA, e.g. "Europe/Vienna"
  get clock(): Clock                                       // now(), and the clock every()/after() run on
  start(): void | Promise<void>
  catalog(): CatalogNode[] | Promise<CatalogNode[]>
  panel(): Panel | undefined | Promise<Panel | undefined>
  panelChanged(): void                                     // tell open pages the panel changed (at most once a second)
  unhandledRejection(reason: unknown): void
  get watch(): WatchView                                   // the chosen signals (watching plugins)
  watched?(values: readonly WatchedValue[], dropped: number): void | Promise<void>
  watchChanged(): void
}

Static declarations on the subclass (PluginClass); all optional:

static readonly config?: z.ZodType      // default: no config (empty object)
static readonly sensors?: readonly SensorClass[]      // ids unique among sensors
static readonly actuators?: readonly ActuatorClass[]  // ids unique among actuators
static readonly watches?: { label: string; description?: string }  // receives values of signals the user chooses
static readonly configVersion?: number  // the config's shape; default 1, raise it with migrateConfig
static migrateConfig?({ config, from, store }: ConfigMigration): unknown  // older config → current shape
static test?(config): Promise<string | void>  // Test connection; read only, throw a message the user can act on
static readonly actions?: readonly ActionClass[]      // see Action
static readonly panelUpdates?: "push"   // the plugin calls panelChanged(); pages then ask for the panel when told, else every 30 s
static discover?(field: string, config: unknown): Promise<Discovered>  // Find for discoverable() fields; read only, at most 15 s

discover runs in a throwaway worker, like test, for a config field marked with discoverable(); config is the form as filled in so far, unvalidated. It answers up to 100 { label, value, detail? }: value is what the field gets when the user picks it. Use Mdns.browse for devices that announce themselves. See Find on the network.

A watching plugin implements watched(values, dropped) (batches, oldest first; the next comes when it returns) and optionally watchChanged(); this.watch.signals() / signal(id) describe the chosen signals. See Watching signals.

type WatchDeclaration = { label: string; description?: string }
interface WatchView { signals(): WatchedSignal[]; signal(id: string): WatchedSignal | undefined }
type WatchedSignal = { id: string; topic: string; label: string; valueType: ValueType | "any"; owner?: { kind: "miniserver" | "plugin"; id: string }; unit?: string; decimals?: number }
type WatchedValue = { signalId: string; ts: number; kind: "state" | "command"; value: Value; forced?: true; initial?: true }

The guide explains each of these: the plugin class, starting and failing, catalog, panel.

Sensor (reference)

abstract class Sensor<P extends Plugin = Plugin, Params = unknown> extends Disposable {
  constructor(readonly plugin: P, readonly params: Params, private readonly output: SensorOutput, readonly signal: SignalInfo = { id: "", label: "" })
  start(): void | Promise<void>
  protected emit(value: Value): void
  protected fail(message: string): void
  protected recover(): void
}

Static declarations (SensorClass):

static readonly id: string                       // required; stored with the signal, never rename
static readonly label?: string                   // default: id
static readonly description?: string             // one sentence the UI shows when adding it
static readonly params?: z.ZodType               // default: empty object; validated before construction
static readonly valueType?: ValueType | "any"    // what emit() sends; default "any"
static readonly unit?: string                    // suggested for new signals, e.g. "W" (up to 16 characters)
static readonly decimals?: number                // suggested for new signals: decimals to show (0-6)
static readonly staleAfterMs?: number            // suggested for new signals: warn after this long without a value

SensorOutput: { emit(value: Value): void; fail(message: string): void; recover?(): void }, the runtime's side, not used by plugin code.

In the guide: Sensors.

Actuator (reference)

abstract class Actuator<P extends Plugin = Plugin, Params = unknown, V extends Value = Value> extends Disposable {
  constructor(readonly plugin: P, readonly params: Params, readonly signal: SignalInfo = { id: "", label: "" })
  start(): void | Promise<void>
  abstract run(value: V, command?: ActuatorCommand): void | Promise<void>
  protected fail(message: string): void
  protected recover(): void
}
interface ActuatorCommand { readonly replayed: boolean }

Static declarations (ActuatorClass):

static readonly id: string                          // required; stored with the signal, never rename
static readonly label?: string                      // default: id
static readonly description?: string                // one sentence the UI shows when adding it
static readonly params?: z.ZodType                  // default: empty object
static readonly accepts?: ValueType | "any"         // wires convert to this before run(); default "any"
static readonly concurrency?: ActuatorConcurrency   // "queue" (default) | "latest"
static readonly unit?: string                       // suggested for new signals, e.g. "%"
static readonly decimals?: number                   // suggested for new signals (0-6)

"latest": while a command runs, only the newest waiting one runs; the replaced ones are reported as superseded (SupersededError, thrown by the runtime, not by plugins).

In the guide: Actuators.

Action (reference)

Something a user starts from the instance page with a small form: pair a device, open a pairing window, remove a paired controller. Declared in the plugin's static actions; the page shows a button per action at the top, and a panel table's rowActions open one with its input filled in. static placement = "panel" takes it off the top: its buttons are then only where the panel puts them, in a section's heading (actions) or on a table row. An input that is a z.discriminatedUnion shows as a choice of its discriminator and the chosen branch's fields.

Static declarations (ActionClass):

static readonly id: string            // required; unique among the plugin's actions
static readonly label?: string        // the button's text; default: id
static readonly description?: string  // one sentence in the dialog
static readonly input?: z.ZodType     // the form; default: no input
static readonly confirm?: string      // asked before it runs, for actions that undo something
static readonly placement?: "toolbar" | "panel"  // "panel": no button at the top, only where the panel puts it

Actions run only while the instance runs or is degraded; a reverse proxy in front of Nexus should allow requests of up to two minutes, or a slow pairing shows as a timeout although it worked.

Disposable (reference)

abstract class Disposable implements DisposableLike {
  static readonly MAX_TIMER_MS: 2_147_483_647
  get isDisposed(): boolean
  dispose(): Promise<void>
  protected onDispose(teardown: Teardown): void
  protected own<T extends DisposableLike>(resource: T): T
  protected useClock(clock: Clock | undefined): void
  protected currentClock(): Clock
  protected every(ms: number, fn: () => void): () => void
  protected after(ms: number, fn: () => void): () => void
  protected listen(emitter: Listenable, event: string | symbol, listener: Listener): void
}

Related types: Clock { now(); setTimeout(fn, ms); clearTimeout(handle); setInterval(fn, ms); clearInterval(handle) } (SystemClock.instance in production, TestClock from /testing in tests), Teardown = () => void | Promise<void>, DisposableLike { dispose(): void | Promise<void> }, Listenable { on(event, listener): unknown; off(event, listener): unknown } (an EventEmitter fits), Listener = (...args: any[]) => void.

In the guide: Lifetimes.

Context objects

/** which configured signal a sensor or actuator is; label "" with hosts that don't send it */
interface SignalInfo { id: string; label: string }
interface PluginContext {
  readonly instanceId: string
  readonly slug?: string
  readonly timeZone?: string
  readonly config: unknown
  readonly log: PluginLogger
  readonly store: PluginStore
  readonly status: PluginStatus
  readonly http: PluginHttp
}
type PluginLogger = Record<"debug" | "info" | "warn" | "error", (message: string, data?: unknown) => void>
interface PluginStore {
  get<T = unknown>(key: string): T | undefined
  set(key: string, value: unknown): void
  delete(key: string): void
  keys(): string[]
}
interface PluginStatus { set(status: "running" | "degraded", message?: string): void }
interface PluginHttp { route(method: string, path: string, handler: HttpHandler): void }
type HttpHandler = (request: HttpRequest) => HttpResponse | Promise<HttpResponse>

In the guide: Logging, store and status and Webhooks. Every number (timeouts, sizes) is in Limits at a glance.

Entry, config and re-exports

@lox-nexus/plugin-sdk/values

In the guide: Values.

Value (reference)

type Value =
  | { type: "null" }
  | { type: "boolean"; value: boolean }
  | { type: "number"; value: number }
  | { type: "string"; value: string }
  | { type: "singleChannel"; value: SingleChannel }
  | { type: "rgbw"; value: Rgbw }
  | { type: "tunableWhite"; value: TunableWhite }
  | { type: "t5"; value: T5 }
type ValueType = Value["type"]
type ValueOf<T extends ValueType> = Extract<Value, { type: T }>
interface SingleChannel { channel: number; fadeTime: number }
interface Rgbw { red: number; green: number; blue: number; white: number; fadeTime: number; flags: number }
interface TunableWhite { temperature: number; brightness: number; fadeTime: number }
interface T5 { buttons: number }

Units: channels and brightness 0-100 (whole percent), fadeTime seconds, temperature Kelvin (conversions keep 2700-6500), flags raw bits (experimental), buttons bitmask 0-31 (experimental).

Value is also an object (an instance of ValueFactory):

Value.null(): ValueOf<"null">
Value.boolean(value: boolean): ValueOf<"boolean">
Value.number(value: number): ValueOf<"number">
Value.string(value: string): ValueOf<"string">
Value.singleChannel(value: SingleChannel): ValueOf<"singleChannel">
Value.rgbw(value: Rgbw): ValueOf<"rgbw">
Value.tunableWhite(value: TunableWhite): ValueOf<"tunableWhite">
Value.t5(value: T5): ValueOf<"t5">
Value.isType(type: string): type is ValueType
Value.equals(a: Value | undefined, b: Value | undefined): boolean
Value.types: readonly ValueType[]

Conversion and helpers (reference)

@lox-nexus/plugin-sdk/testing

In the guide: Testing.

PluginTestHost (reference)

class PluginTestHost<T extends PluginClass = PluginClass> {
  readonly sent: WorkerMessage[]
  readonly store: Record<string, unknown>
  get plugin(): InstanceType<T>
  static start<T extends PluginClass>(type: T, options?: TestHostOptions): Promise<PluginTestHost<T>>
  static describe(type: PluginClass): Promise<PluginDescription>
  static checkConfig(type: PluginClass, config: unknown, configVersion?: number, store?: Record<string, unknown>): Promise<ConfigCheckResult>
  static testConfig(type: PluginClass, config: unknown): Promise<string | undefined>
  static discover(type: PluginClass, field: string, config?: unknown): Promise<Discovered>
  addSensor(capability: string, params?: unknown, label?: string): Promise<string>
  addActuator(capability: string, params?: unknown, label?: string): Promise<string>
  remove(id: string): Promise<void>
  values(id: string): Value[]
  next(id: string, timeoutMs?: number): Promise<Value>
  actuate(id: string, value: Value, causeId?: string, replayed?: boolean): Promise<void>
  catalog(): Promise<CatalogNode[]>
  panel(): Promise<Panel | undefined>
  http(request: Partial<HttpRequest> & Pick<HttpRequest, "path">): Promise<Required<HttpResponse>>
  action(id: string, input?: unknown): Promise<string | undefined>  // runs an action like its button; resolves with its message, rejects with its failure
  actionAnswer(id: string, input?: unknown): Promise<ActionAnswer | undefined>  // the whole answer: text, or { message?, panel? }
  get status(): { status: "running" | "degraded"; message?: string }
  watchSignals(signals: WatchedSignal[]): Promise<void>
  pushValues(values: Array<Omit<WatchedValue, "ts" | "kind"> & Partial<Pick<WatchedValue, "ts" | "kind">>>, dropped?: number): Promise<void>
  stop(): Promise<void>
}
interface ConfigCheckResult { issues: ConfigIssue[]; config: unknown; version: number; store?: { set: Record<string, unknown>; delete: string[] } }
interface ConfigIssue { path: (string | number)[]; message: string }
interface TestHostOptions {
  config?: unknown; store?: Record<string, unknown>; instanceId?: string; slug?: string /* default "test" */; clock?: Clock /* e.g. a TestClock */
  timeZone?: string; forwardRejections?: boolean; configVersion?: number
  hostFeatures?: string[]  // default all (HOST_FEATURES); [] shows what an older Nexus gets
}
function cellText(cell: Cell | undefined): string  // a panel cell's text, for assertions

class TestClock implements Clock {
  constructor(start?: number | string | Date)
  get pending(): number
  advance(ms: number): Promise<void>       // runs each due timer at its own due time
  advanceTo(time: number | string | Date): Promise<void>
  jump(ms: number): void                   // a wall-clock step; timers keep their remaining delay
}

PluginRuntimeForTests is internal (its constructor may change); don't use it.

@lox-nexus/plugin-sdk/wire

Plugin authors need only the shapes (reference):

interface CatalogNode { label: string; id?: string; children?: CatalogNode[]; entries?: CatalogEntry[] }  // id: for a panel's "Signals" button
type CatalogEntry = { kind: "sensor" | "actuator"; capability: string; params: unknown; label: string; value?: Value; unit?: string }
type Tone = "ok" | "warn" | "error" | "info" | "muted"
type Cell = string | { text?: string; tone?: Tone; until?: number; since?: number; at?: number }  // epoch ms, counted live: "in 12:30", "for 3 min", "12 s ago"
type PanelPart =
  | { type: "keyValue"; items: { label: string; value: Cell; control?: RowAction; catalog?: string }[] }
  | { type: "table"; columns: string[]; rows: Cell[][]; rowActions?: RowAction[][]; rowCatalog?: (string | null)[] }  // up to 4 buttons per row; catalog node ids
  | { type: "tiles"; tiles: { label: string; value: number | string | null; unit?: string; decimals?: number; tone?: Tone; min?: number; max?: number; until?: number; hint?: string }[] }  // at most 12
  | { type: "notice"; tone: Tone; title?: string; text: string; link?: { label: string; href: string } }  // href: http(s) or "#/…"
  | { type: "qr"; data: string; caption?: string }  // e.g. a Matter pairing payload; hosts before it refuse the panel
  | { type: "json"; data: unknown }
type Panel = PanelPart | { type: "sections"; sections: { title: string; panel: PanelPart; actions?: RowAction[] }[] }  // at most 20 sections; up to 4 buttons in a heading
type RowAction = { action: string; label?: string; input?: Record<string, unknown>; instant?: boolean; switch?: { checked: boolean } }
type ActionAnswer = string | { message?: string; panel?: PanelPart }
type Discovered = { label: string; value: string; detail?: string }[]  // at most 100
type HttpRequest = { method: string; path: string; query: Record<string, string>; headers: Record<string, string>; body: string }
type HttpResponse = { status: number; headers?: Record<string, string>; body?: string }
type PluginHealth = "running" | "degraded"
type LogLevel = "debug" | "info" | "warn" | "error"

Messages. Host and worker talk in these messages (type tells them apart). A plugin never sends them itself; the runtime does. Requests carry a requestId and are answered with response { requestId, ok, result?, error? }.

For hosts and tools: WIRE_VERSION (1), HOST_FEATURES (HostFeature), HostMessageSchema, WorkerMessageSchema, SignalSpecSchema, HttpRequestSchema, HttpResponseSchema, CatalogEntrySchema, CatalogNodeSchema, PanelSchema, PanelPartSchema, RowActionSchema, CellSchema, ToneSchema, ActionAnswerSchema, DiscoveredSchema, CapabilityDescriptionSchema, PluginDescriptionSchema, PluginHealthSchema, LogLevelSchema, the matching types (HostMessage, WorkerMessage, SignalSpec, CapabilityDescription, PluginDescription, JsonSchema) and PluginWorkerData.