Integration SDK API

interface DeviceDescriptor {
  /** Stable per-device id (serial, MAC). Entities sharing it group under one device. */
  uniqueId?: string;
  manufacturer?: string;
  model?: string;
  name?: string;
  swVersion?: string;
  hwVersion?: string;
}

interface EntityDescriptor {
  /** Stable id within this integration (never changes for the same physical thing). */
  uniqueId: string;
  platform: Platform;
  name: string;
  deviceClass?: string | null;
  /** Platform feature bitmask (e.g. cover SET_POSITION). Omit for the default. */
  supportedFeatures?: number;
  state?: EntityState;
  attributes?: Record<string, unknown>;
  available?: boolean;
  entityCategory?: 'config' | 'diagnostic' | null;
  device?: DeviceDescriptor;
  /**
   * Handle a service call aimed at THIS entity (turnOn, setCoverPosition,
   * selectOption, …). Falls back to the integration's `handleService`.
   */
  onService?: (service: string, data: Record<string, unknown>, ctx: NovonSdk) => void | Promise<void>;
}

interface EntityUpdate {
  state?: EntityState;
  attributes?: Record<string, unknown>;
  available?: boolean;
}

interface HttpRequestOptions {
  url?: string;
  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
  headers?: Record<string, string>;
  /** A string is sent as-is; an object is JSON-encoded with a JSON content-type. */
  body?: string | Record<string, unknown> | unknown[];
  /** Capped by the hub (30 s). Default 15 s. */
  timeoutMs?: number;
}

interface HttpResponse {
  ok: boolean;
  status: number;
  headers: Record<string, string>;
  body: string;
  text(): string;
  json<T = unknown>(): T;
}

interface EntryContext {
  entryId: string;
  title: string;
  domain: string;
  version: string;
  /** Values of config-flow inputs scoped `data` (identity: host, credentials). */
  data: Record<string, unknown>;
  /** Values of inputs scoped `options` (tunables; editable after install). */
  options: Record<string, unknown>;
}

interface ServiceCallInfo {
  uniqueId: string;
  platform?: Platform;
  service: string;
  data: Record<string, unknown>;
}

interface IntegrationDefinition {
  /**
   * Called once per config entry when it loads (boot, install, reload).
   * Connect to the device, register entities with `ctx.entities.add`, start
   * polling with `setInterval`. Throw `ctx.notReady('...')` to have the hub
   * retry later with backoff; any other throw marks the entry FAILED.
   */
  setupEntry(ctx: NovonSdk): void | Promise<void>;
  /** Called before the entry unloads. Timers are cleared for you. */
  unloadEntry?(ctx: NovonSdk): void | Promise<void>;
  /** Service call for an entity that has no `onService` of its own. */
  handleService?(call: ServiceCallInfo, ctx: NovonSdk): void | Promise<void>;
  /**
   * The user changed the entry's options. Return normally to keep running with
   * `ctx.entry` already updated. When absent, the hub RELOADS the entry.
   */
  optionsUpdated?(ctx: NovonSdk, previous: { data: Record<string, unknown>; options: Record<string, unknown> }): void | Promise<void>;
}

interface NovonSdk {
  defineIntegration(definition: IntegrationDefinition): IntegrationDefinition;
  /** The config entry this isolate serves (set before `setupEntry`). */
  readonly entry: EntryContext;
  entities: {
    add(descriptors: EntityDescriptor | EntityDescriptor[]): Promise<void>;
    update(uniqueId: string, patch: EntityUpdate): void;
    remove(uniqueId: string): Promise<void>;
    list(): string[];
  };
  /** Outbound HTTP(S). Requires the `http` permission. Loopback / link-local are refused. */
  http(url: string, init?: Omit<HttpRequestOptions, 'url'>): Promise<HttpResponse>;
  http(options: HttpRequestOptions): Promise<HttpResponse>;
  /** Persistent per-entry key/value storage (JSON values ≤ 64 KiB). Requires `kv`. */
  kv: {
    get<T = unknown>(key: string): T | undefined | null;
    set(key: string, value: unknown): void;
    delete(key: string): void;
  };
  /** Build the error that makes the hub retry setup later (device offline, …). */
  notReady(message?: string): Error;
  sleep(ms: number): Promise<void>;
}

type Platform = 'sensor' | 'binary_sensor' | 'switch' | 'light' | 'cover' | 'lock' | 'select';

type EntityState = string | number | boolean | null;

// Ambient declarations for code that runs INSIDE the hub's isolate.
//
// Reference this file from an integration's tsconfig ("types" or a
// `/// <reference types="@novon/integration-sdk/globals" />` line) so `novon`,
// `console` and the timers type-check without importing anything — the
// bundle must not import at runtime; the hub injects these globals.

import type { NovonSdk } from './index';

declare global {
  const novon: NovonSdk;

  function setTimeout(handler: (...args: unknown[]) => void, timeoutMs?: number, ...args: unknown[]): number;
  function setInterval(handler: (...args: unknown[]) => void, intervalMs?: number, ...args: unknown[]): number;
  function clearTimeout(id: number | undefined): void;
  function clearInterval(id: number | undefined): void;

  const console: {
    log(...args: unknown[]): void;
    info(...args: unknown[]): void;
    warn(...args: unknown[]): void;
    error(...args: unknown[]): void;
    debug(...args: unknown[]): void;
  };
}

export {};