homebridge/dist/matter/config.d.ts

HomeKit support for the impatient

/**
 * Lightweight Matter Configuration Utilities
 *
 * This module provides config collection and validation without importing
 * heavy Matter.js libraries. This ensures fast startup for users without
 * Matter configured.
 */
import type { HomebridgeConfig } from '../bridgeService.js';
import type { MatterConfig } from './types.js';
/**
 * Whether a Matter config block represents an *enabled* Matter setup.
 * The block being present means Matter is configured; `enabled: false` means
 * it is configured but intentionally turned off (storage + port preserved so
 * it can be re-enabled without re-commissioning). Missing `enabled` = enabled,
 * which keeps every pre-existing config working unchanged.
 *
 * Note: this does NOT distinguish "the main matter server should start" from
 * "the matter API surface should be exposed to plugins". Use
 * `shouldStartMatterServer` for the former — it additionally accounts for
 * externalsOnly mode, where the API is exposed but the bridge server is not
 * started.
 */
export declare function isMatterConfigEnabled(matter: MatterConfig | undefined): boolean;
/**
 * Whether the main Matter server should start for this bridge — i.e. Matter
 * is configured, enabled, and NOT in externalsOnly mode. In externalsOnly
 * mode the API is still loaded (so plugins can publish externals via their
 * own per-accessory MatterServer instances) but the bridge aggregator does
 * not come up.
 */
export declare function shouldStartMatterServer(matter: MatterConfig | undefined): boolean;
/**
 * Whether Matter is "active" for this bridge in any form — either fully on,
 * or in externalsOnly mode (api.matter loaded, manager listening for external
 * publish events, main bridge server NOT started). Returns false only when
 * matter is missing or fully disabled (`enabled: false` without `externalsOnly`).
 *
 * Use this for gates like "should api.matter be loaded?" and "should the
 * matter manager be constructed?". Use `shouldStartMatterServer` for the
 * tighter gate of "should the bridge aggregator come up?".
 */
export declare function isMatterActive(matter: MatterConfig | undefined): boolean;
/**
 * Normalise the coherence of `matter.externalsOnly` for a single bridge block.
 *
 * `externalsOnly: true` is meant to be paired with `enabled: false` (the two
 * flags together confirm "bridge node off, externals still publish"). If a
 * config sets `externalsOnly: true` on its own we honour the unambiguous
 * intent rather than failing the whole process — we warn and set
 * `enabled: false` in place so the block matches the canonical externalsOnly
 * form every downstream check expects. This mirrors the log-and-continue
 * behaviour of the port validators rather than taking the whole instance down
 * over one stray flag.
 *
 * For accessory child bridges, callers should use
 * `stripMatterExternalsOnlyForAccessory` instead — externals are not
 * supported on accessory plugins, so the field is dropped with a warning
 * before this check runs.
 *
 * Mutates the passed matter block in place.
 */
export declare function validateMatterExternalsOnly(matter: MatterConfig, bridgeLabel: string): void;
/**
 * Strip `matter.externalsOnly` (if set) from an accessory child bridge's
 * matter block, logging a warning. Externals are not supported via the
 * accessory plugin API, so the flag is meaningless there — mirrors the
 * accessory-side behaviour of `hap.externalsOnly`.
 *
 * Mutates the passed matter block in place.
 */
export declare function stripMatterExternalsOnlyForAccessory(matter: MatterConfig, bridgeLabel: string): void;
/**
 * Lightweight config collector that doesn't require Matter.js imports
 */
export declare class MatterConfigCollector {
    /**
     * Check if any Matter configuration exists in the config
     */
    static hasMatterConfig(config: HomebridgeConfig): boolean;
    /**
     * Collect all configured Matter ports from config to avoid conflicts.
     *
     * Ports are collected from every bridge block that declares one, regardless
     * of `enabled`/`externalsOnly` state. This is deliberate: a disabled-in-place
     * bridge (`enabled: false`) keeps its configured port reserved so that
     * re-enabling it later reuses the same port (no re-commissioning) and the
     * allocator never hands that port to an automatic Matter/external allocation
     * in the meantime. The trade-off is that a disabled bridge's port stays
     * unavailable for auto-allocation even though no server currently binds it —
     * that is the cost of the "port preserved" contract on `enabled`.
     */
    static collectConfiguredMatterPorts(config: HomebridgeConfig): number[];
    /**
     * Validate the matterPorts pool configuration
     * Ensures start and end are defined and start <= end
     *
     * @param config - The Homebridge configuration
     */
    static validateMatterPortsPool(config: HomebridgeConfig): void;
    /**
     * Validate Matter configuration (lazy-loads validator only when needed)
     * This function dynamically imports the full validator to avoid loading it
     * when Matter is not configured.
     */
    static validateMatterConfig(config: HomebridgeConfig): Promise<void>;
    /**
     * Check for port conflicts between main bridge and child bridges
     *
     * @param config - The Homebridge configuration
     */
    private static checkPortConflicts;
}
//# sourceMappingURL=config.d.ts.map