homebridge 2.0.0-beta.4 → 2.0.0-beta.40

package/dist/matter/server.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Matter.js Server Implementation for Homebridge Plugin API
+ *
+ * This provides a Matter bridge that plugins can use to register
+ * Matter accessories via the Homebridge API.
+ */
+import type { SerializedMatterAccessory } from './accessoryCache.js';
+import { EventEmitter } from 'node:events';
+import * as clusters from '@matter/main/clusters';
+import { MatterServerConfig } from './sharedTypes.js';
+import { deviceTypes, MatterAccessory, MatterServerEvents } from './types.js';
+/**
+ * Matter Server for Homebridge Plugin API
+ * Allows plugins to register Matter accessories explicitly
+ */
+export declare class MatterServer extends EventEmitter {
+    on: <K extends keyof MatterServerEvents>(event: K, listener: MatterServerEvents[K]) => this;
+    emit: <K extends keyof MatterServerEvents>(event: K, ...args: Parameters<MatterServerEvents[K]>) => boolean;
+    removeListener: <K extends keyof MatterServerEvents>(event: K, listener: MatterServerEvents[K]) => this;
+    removeAllListeners: (event?: keyof MatterServerEvents) => this;
+    private readonly config;
+    private serverNode;
+    private aggregator;
+    private accessories;
+    private readonly behaviorRegistry;
+    private isRunning;
+    private readonly MAX_DEVICES;
+    private shutdownHandler;
+    private static readonly CLUSTER_BEHAVIOR_MAP;
+    private passcode;
+    private discriminator;
+    private readonly vendorId;
+    private readonly productId;
+    private commissioningInfo;
+    private serialNumber?;
+    private cleanupHandlers;
+    private storageManager;
+    private matterStoragePath?;
+    private accessoryCache;
+    constructor(config: MatterServerConfig);
+    /**
+     * Validate and sanitize Matter server configuration
+     * Throws descriptive errors if configuration is invalid
+     */
+    private validateAndSanitizeConfig;
+    /**
+     * Generate a secure random passcode
+     * According to Matter spec, passcode must be:
+     * - 8 digits (00000001 to 99999998)
+     * - Not in the invalid list
+     * - Not sequential or repeating patterns
+     */
+    private generateSecurePasscode;
+    /**
+     * Validate a passcode according to Matter specifications
+     */
+    private isValidPasscode;
+    /**
+     * Generate a random discriminator
+     * According to Matter spec, discriminator must be:
+     * - 12 bits (0-4095)
+     * - Should be random for security
+     */
+    private generateRandomDiscriminator;
+    /**
+     * Create ServerNode with automatic recovery from corrupted storage
+     *
+     * Matter.js can fail to start if fabric data is corrupted (common after
+     * hard shutdowns or disk errors). This method implements automatic recovery by:
+     *
+     * 1. Attempting normal ServerNode creation
+     * 2. If it fails with storage errors, identifying and removing corrupted files
+     * 3. Retrying ServerNode creation with fresh storage
+     *
+     * This prevents the need for manual intervention while preserving data
+     * safety by only removing storage on confirmed corruption errors.
+     *
+     * @param nodeOptions - Matter.js ServerNode configuration
+     * @param sanitizedId - Filesystem-safe bridge identifier
+     * @returns Initialized ServerNode instance
+     * @throws Error if recovery fails or error is not storage-related
+     */
+    private createServerNodeWithRecovery;
+    /**
+     * Start the Matter server
+     */
+    start(): Promise<void>;
+    /**
+     * Run the server after devices have been added (for external accessory mode)
+     *
+     * This must be called after registerPlatformAccessories() when using externalAccessory mode.
+     * In bridge mode, the server starts automatically when accessories are registered.
+     *
+     * @throws {MatterDeviceError} If server node is not initialized or server is already running
+     * @example
+     * ```typescript
+     * await matterServer.start()
+     * await matterServer.registerPlatformAccessories('plugin', 'platform', accessories)
+     * await matterServer.runServer() // External accessory mode only
+     * ```
+     */
+    runServer(): Promise<void>;
+    /**
+     * Set up and validate storage
+     */
+    private setupStorage;
+    /**
+     * Load or generate commissioning credentials (passcode and discriminator)
+     * These must be persistent across restarts to maintain the same QR code
+     */
+    private loadOrGenerateCredentials;
+    /**
+     * Generate and display commissioning information
+     */
+    private generateCommissioningInfo;
+    /**
+     * Wait for the server to be ready
+     */
+    private waitForServerReady;
+    /**
+     * Set up Matter.js commissioning event listeners
+     * Uses native Matter.js events instead of file watching for reliability
+     */
+    private setupCommissioningEventListeners;
+    /**
+     * Update commissioning info file when commissioning state changes
+     */
+    private updateCommissioningFile;
+    /**
+     * Register Matter platform accessories (Plugin API - matches HAP pattern)
+     *
+     * Registers Matter accessories from a dynamic platform plugin. Accessories are stored
+     * and automatically restored on server restart.
+     *
+     * @param pluginIdentifier - The plugin identifier (e.g., 'homebridge-example')
+     * @param platformName - The platform name from config.json
+     * @param accessories - Array of Matter accessories to register
+     * @throws {MatterDeviceError} If maximum device limit is reached or accessory is invalid
+     * @see {@link MatterAccessory} for accessory structure
+     */
+    registerPlatformAccessories(pluginIdentifier: string, platformName: string, accessories: MatterAccessory[]): Promise<void>;
+    /**
+     * Unregister Matter platform accessories (Plugin API - matches HAP pattern)
+     */
+    unregisterPlatformAccessories(pluginIdentifier: string, platformName: string, accessories: MatterAccessory[]): Promise<void>;
+    /**
+     * Update Matter platform accessories in the cache
+     * Similar to api.updatePlatformAccessories() for HAP accessories
+     *
+     * This updates the cached accessory information without unregistering and re-registering.
+     * Useful when device metadata changes (name, manufacturer, firmware version, etc.)
+     */
+    updatePlatformAccessories(accessories: MatterAccessory[]): Promise<void>;
+    /**
+     * Register a single Matter accessory (internal method)
+     */
+    private registerAccessory;
+    /**
+     * Restore cached state for an accessory
+     */
+    private restoreCachedState;
+    /**
+     * Detect cluster features for an accessory
+     * Returns an object containing detected features for various clusters
+     */
+    private detectClusterFeatures;
+    /**
+     * Build custom behaviors for an accessory based on handlers
+     */
+    private buildCustomBehaviors;
+    /**
+     * Create endpoint options for an accessory
+     */
+    private createEndpointOptions;
+    /**
+     * Register command handlers for an accessory
+     */
+    private registerAccessoryHandlers;
+    /**
+     * Create and register child endpoints (parts) for an accessory
+     */
+    private createAccessoryParts;
+    /**
+     * Finalize accessory registration (store, emit events, save cache)
+     */
+    private finalizeAccessoryRegistration;
+    /**
+     * Unregister a Matter accessory (Plugin API)
+     */
+    unregisterAccessory(uuid: string): Promise<void>;
+    /**
+     * Update a Matter accessory's state (Plugin API)
+     *
+     * This method can be called from anywhere, including from within handlers.
+     * State updates are automatically deferred to avoid transaction conflicts.
+     *
+     * @param uuid - The UUID of the accessory
+     * @param cluster - The cluster name
+     * @param attributes - The attributes to update
+     * @param partId - Optional: ID of the part to update (for composed devices)
+     */
+    updateAccessoryState(uuid: string, cluster: string, attributes: Record<string, unknown>, partId?: string): Promise<void>;
+    /**
+     * Get a Matter accessory's current state (Plugin API)
+     *
+     * Returns the current cluster attribute values that are exposed to Matter controllers.
+     * This is useful for:
+     * - Reading state after plugin restart (when local variables are lost)
+     * - Verifying current state before making changes
+     * - Multiple parts of code that need to read state
+     * - Debugging and logging
+     *
+     * @param uuid - The UUID of the accessory
+     * @param cluster - The cluster name (e.g., 'onOff', 'levelControl')
+     * @param partId - Optional: ID of the part to get state from (for composed devices)
+     * @returns Current cluster attribute values, or undefined if cluster not found
+     */
+    getAccessoryState(uuid: string, cluster: string, partId?: string): Record<string, unknown> | undefined;
+    /**
+     * Get all cached accessories (Internal - for restore process)
+     * @internal
+     */
+    getAllCachedAccessories(): SerializedMatterAccessory[];
+    /**
+     * Get all registered accessories (Plugin API)
+     */
+    getAccessories(): MatterAccessory[];
+    /**
+     * Get a specific accessory by UUID (Plugin API)
+     */
+    getAccessory(uuid: string): MatterAccessory | undefined;
+    /**
+     * Stop the Matter server
+     */
+    stop(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    private cleanup;
+    /**
+     * Get fabric information for commissioned controllers
+     *
+     * Returns information about each paired controller (fabric) including:
+     * - fabricIndex: Unique identifier for the fabric
+     * - fabricId: 64-bit fabric identifier
+     * - nodeId: Node identifier within the fabric
+     * - rootVendorId: Vendor ID of the root node
+     * - label: Optional human-readable label
+     *
+     * @returns Array of fabric information objects, or empty array if no fabrics are commissioned
+     * @example
+     * ```typescript
+     * const fabrics = matterServer.getFabricInfo()
+     * console.log(`Commissioned to ${fabrics.length} controller(s)`)
+     * fabrics.forEach(fabric => {
+     *   console.log(`  Fabric ${fabric.fabricIndex}: ${fabric.label || 'Unnamed'}`)
+     * })
+     * ```
+     */
+    getFabricInfo(): Array<{
+        fabricIndex: number;
+        fabricId: string;
+        nodeId: string;
+        rootVendorId: number;
+        label?: string;
+    }>;
+    /**
+     * Check if the server is commissioned
+     */
+    isCommissioned(): boolean;
+    /**
+     * Get the number of commissioned fabrics
+     */
+    getCommissionedFabricCount(): number;
+    /**
+     * Get server status information
+     */
+    getServerInfo(): {
+        running: boolean;
+        port: number;
+        deviceCount: number;
+        commissioned: boolean;
+        fabricCount: number;
+        serialNumber?: string;
+    };
+    /**
+     * Get commissioning information
+     */
+    getCommissioningInfo(): {
+        qrCode?: string;
+        manualPairingCode?: string;
+        serialNumber?: string;
+        passcode?: number;
+        discriminator?: number;
+        commissioned: boolean;
+    };
+    /**
+     * Get storage statistics
+     */
+    getStorageStats(): Array<{
+        entries: number;
+        namespace: string;
+        path: string;
+    }> | null;
+    /**
+     * Check if server is running
+     */
+    isServerRunning(): boolean;
+    /**
+     * Get Matter device types available for plugin use
+     */
+    getDeviceTypes(): typeof deviceTypes;
+    /**
+     * Get Matter clusters available for plugin use
+     */
+    getClusters(): typeof clusters;
+    /**
+     * Remove a specific fabric (controller) from the bridge
+     * This decommissions a single controller while leaving others intact
+     *
+     * @param fabricIndex - The fabric index to remove
+     * @returns Promise that resolves when the fabric is removed
+     */
+    removeFabric(fabricIndex: number): Promise<void>;
+    /**
+     * Check if a specific fabric exists
+     */
+    hasFabric(fabricIndex: number): boolean;
+    /**
+     * Notify controllers that the parts list has changed
+     * This triggers controllers (like Home app) to re-read the device list
+     * and discover new or removed accessories without needing to re-pair
+     */
+    private notifyPartsListChanged;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/matter/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/matter/server.ts"],"names":[],"mappings":"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"}