homebridge-myleviton 3.0.0

package/dist/api/persistence.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Device state persistence for faster startup and offline resilience
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevicePersistence = exports.PERSISTENCE_FILE_NAME = exports.DEFAULT_PERSISTENCE_CONFIG = void 0;
+exports.getDevicePersistence = getDevicePersistence;
+exports.resetGlobalPersistence = resetGlobalPersistence;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Default persistence configuration
+ */
+exports.DEFAULT_PERSISTENCE_CONFIG = {
+    maxAge: 24 * 60 * 60 * 1000, // 24 hours
+    maxDevices: 200,
+};
+/**
+ * Default persistence file name
+ */
+exports.PERSISTENCE_FILE_NAME = '.homebridge-myleviton-state.json';
+/**
+ * Device state persistence manager
+ * Stores device states for faster startup and offline resilience
+ */
+class DevicePersistence {
+    storagePath;
+    maxAge;
+    maxDevices;
+    deviceStates = new Map();
+    loaded = false;
+    dirty = false;
+    constructor(storagePath, config = {}) {
+        const merged = { ...exports.DEFAULT_PERSISTENCE_CONFIG, ...config };
+        this.storagePath = storagePath || path.join(process.env.HOME || '/tmp', exports.PERSISTENCE_FILE_NAME);
+        this.maxAge = merged.maxAge ?? 24 * 60 * 60 * 1000;
+        this.maxDevices = merged.maxDevices ?? 200;
+    }
+    /**
+     * Load persisted device states from disk
+     */
+    load() {
+        if (this.loaded) {
+            return this.deviceStates;
+        }
+        try {
+            if (fs.existsSync(this.storagePath)) {
+                const data = fs.readFileSync(this.storagePath, 'utf8');
+                const parsed = JSON.parse(data);
+                // Validate structure
+                if (parsed && typeof parsed === 'object' && parsed.devices) {
+                    const now = Date.now();
+                    const maxAge = this.maxAge;
+                    for (const [id, state] of Object.entries(parsed.devices)) {
+                        if (state && typeof state === 'object') {
+                            // Check if data is too old
+                            const cachedAt = parsed.timestamp || 0;
+                            if (now - cachedAt < maxAge) {
+                                this.deviceStates.set(id, {
+                                    ...state,
+                                    _cached: true,
+                                    _cachedAt: cachedAt,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore load errors - start fresh
+            this.deviceStates.clear();
+        }
+        this.loaded = true;
+        return this.deviceStates;
+    }
+    /**
+     * Save device states to disk
+     */
+    save() {
+        if (!this.dirty && this.loaded) {
+            return true; // Nothing to save
+        }
+        try {
+            // Clean up internal properties before saving
+            const devices = {};
+            // Limit size
+            let count = 0;
+            for (const [id, state] of this.deviceStates.entries()) {
+                if (count >= this.maxDevices) {
+                    break;
+                }
+                const { _cached, _cachedAt, _updatedAt, ...cleanState } = state;
+                devices[id] = cleanState;
+                count++;
+            }
+            const data = JSON.stringify({
+                version: 1,
+                timestamp: Date.now(),
+                devices,
+            }, null, 2);
+            // Write atomically using temp file
+            const tempPath = `${this.storagePath}.tmp`;
+            fs.writeFileSync(tempPath, data, 'utf8');
+            fs.renameSync(tempPath, this.storagePath);
+            this.dirty = false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Update state for a device
+     */
+    updateDevice(deviceId, state) {
+        if (!deviceId) {
+            return;
+        }
+        const existing = this.deviceStates.get(deviceId) || { id: deviceId };
+        this.deviceStates.set(deviceId, {
+            ...existing,
+            ...state,
+            id: deviceId,
+            _cached: false,
+            _updatedAt: Date.now(),
+        });
+        this.dirty = true;
+    }
+    /**
+     * Update device from API status
+     */
+    updateFromStatus(deviceId, status) {
+        this.updateDevice(deviceId, {
+            power: status.power,
+            brightness: status.brightness,
+        });
+    }
+    /**
+     * Get cached state for a device
+     */
+    getDevice(deviceId) {
+        this.load(); // Ensure loaded
+        return this.deviceStates.get(deviceId) || null;
+    }
+    /**
+     * Check if device has fresh cached data
+     */
+    hasFreshCache(deviceId, maxAge = this.maxAge) {
+        const state = this.getDevice(deviceId);
+        if (!state) {
+            return false;
+        }
+        const updatedAt = state._updatedAt || state._cachedAt || 0;
+        return Date.now() - updatedAt < maxAge;
+    }
+    /**
+     * Get device status from cache (for fallback)
+     */
+    getCachedStatus(deviceId) {
+        const state = this.getDevice(deviceId);
+        if (!state || !state.power) {
+            return null;
+        }
+        return {
+            id: state.id,
+            power: state.power,
+            brightness: state.brightness,
+        };
+    }
+    /**
+     * Remove a device from persistence
+     */
+    removeDevice(deviceId) {
+        const deleted = this.deviceStates.delete(deviceId);
+        if (deleted) {
+            this.dirty = true;
+        }
+        return deleted;
+    }
+    /**
+     * Clear all persisted states
+     */
+    clear() {
+        this.deviceStates.clear();
+        this.dirty = true;
+        try {
+            if (fs.existsSync(this.storagePath)) {
+                fs.unlinkSync(this.storagePath);
+            }
+        }
+        catch {
+            // Ignore delete errors
+        }
+    }
+    /**
+     * Get all cached device states
+     */
+    getAllDevices() {
+        this.load();
+        return new Map(this.deviceStates);
+    }
+    /**
+     * Get device count
+     */
+    get size() {
+        return this.deviceStates.size;
+    }
+    /**
+     * Check if persistence has been modified
+     */
+    get isDirty() {
+        return this.dirty;
+    }
+    /**
+     * Get persistence statistics
+     */
+    getStats() {
+        return {
+            deviceCount: this.size,
+            loaded: this.loaded,
+            dirty: this.dirty,
+            storagePath: this.storagePath,
+        };
+    }
+}
+exports.DevicePersistence = DevicePersistence;
+/**
+ * Global persistence instance
+ */
+let globalPersistence = null;
+/**
+ * Get or create the global persistence instance
+ */
+function getDevicePersistence(storagePath) {
+    if (!globalPersistence) {
+        globalPersistence = new DevicePersistence(storagePath);
+    }
+    return globalPersistence;
+}
+/**
+ * Reset the global persistence (for testing)
+ */
+function resetGlobalPersistence() {
+    globalPersistence = null;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/api/persistence.js.map

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

package/dist/api/rate-limiter.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Token bucket rate limiter for API requests
+ */
+/**
+ * Rate limiter configuration
+ */
+export interface RateLimiterConfig {
+    /** Maximum requests per window */
+    maxRequests: number;
+    /** Window duration in milliseconds */
+    windowMs: number;
+    /** Whether to wait when rate limited (vs throwing immediately) */
+    waitOnLimit?: boolean;
+    /** Maximum wait time when waitOnLimit is true */
+    maxWaitMs?: number;
+}
+/**
+ * Default rate limiter configuration
+ * Leviton allows max 99 devices per residence, 20 residences per account
+ * At startup: 99 devices × 2 queries (power + brightness) = 198 requests
+ * Rate limiter only applies to WRITE operations
+ */
+export declare const DEFAULT_RATE_LIMITER_CONFIG: RateLimiterConfig;
+/**
+ * Token bucket rate limiter
+ * Prevents overwhelming the Leviton API with too many requests
+ */
+export declare class RateLimiter {
+    private readonly maxRequests;
+    private readonly windowMs;
+    private readonly waitOnLimit;
+    private readonly maxWaitMs;
+    private requests;
+    constructor(config?: Partial<RateLimiterConfig>);
+    /**
+     * Clean up expired request timestamps
+     */
+    private cleanup;
+    /**
+     * Get current request count in window
+     */
+    get currentCount(): number;
+    /**
+     * Get remaining requests in window
+     */
+    get remaining(): number;
+    /**
+     * Get time until window resets (oldest request expires)
+     */
+    get resetTime(): number;
+    /**
+     * Check if a request can be made without blocking
+     */
+    canAcquire(): boolean;
+    /**
+     * Try to acquire a request token
+     * @returns true if acquired, false if rate limited
+     */
+    tryAcquire(): boolean;
+    /**
+     * Acquire a request token, throwing if rate limited
+     * @throws RateLimitError if rate limited and waitOnLimit is false
+     */
+    acquire(): void;
+    /**
+     * Acquire a request token, waiting if necessary
+     * @throws RateLimitError if wait exceeds maxWaitMs
+     */
+    acquireAsync(): Promise<void>;
+    /**
+     * Execute a function with rate limiting
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Reset the rate limiter
+     */
+    reset(): void;
+    /**
+     * Get rate limiter status for monitoring
+     */
+    getStatus(): {
+        currentCount: number;
+        maxRequests: number;
+        remaining: number;
+        resetTime: number;
+        windowMs: number;
+    };
+}
+/**
+ * Get or create the global rate limiter
+ */
+export declare function getRateLimiter(config?: Partial<RateLimiterConfig>): RateLimiter;
+/**
+ * Reset the global rate limiter (for testing)
+ */
+export declare function resetGlobalRateLimiter(): void;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/api/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/api/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAKzC,CAAA;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAe;gBAEnB,MAAM,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAQnD;;OAEG;IACH,OAAO,CAAC,OAAO;IAKf;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAGzB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAItB;IAED;;OAEG;IACH,UAAU,IAAI,OAAO;IAKrB;;;OAGG;IACH,UAAU,IAAI,OAAO;IAWrB;;;OAGG;IACH,OAAO,IAAI,IAAI;IAUf;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBnC;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASlD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,SAAS,IAAI;QACX,YAAY,EAAE,MAAM,CAAA;QACpB,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,EAAE,MAAM,CAAA;KACjB;CASF;AAOD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,WAAW,CAK/E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/api/rate-limiter.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Token bucket rate limiter for API requests
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = exports.DEFAULT_RATE_LIMITER_CONFIG = void 0;
+exports.getRateLimiter = getRateLimiter;
+exports.resetGlobalRateLimiter = resetGlobalRateLimiter;
+const errors_1 = require("../errors");
+const retry_1 = require("../utils/retry");
+/**
+ * Default rate limiter configuration
+ * Leviton allows max 99 devices per residence, 20 residences per account
+ * At startup: 99 devices × 2 queries (power + brightness) = 198 requests
+ * Rate limiter only applies to WRITE operations
+ */
+exports.DEFAULT_RATE_LIMITER_CONFIG = {
+    maxRequests: 300,
+    windowMs: 60000, // 1 minute
+    waitOnLimit: false,
+    maxWaitMs: 30000,
+};
+/**
+ * Token bucket rate limiter
+ * Prevents overwhelming the Leviton API with too many requests
+ */
+class RateLimiter {
+    maxRequests;
+    windowMs;
+    waitOnLimit;
+    maxWaitMs;
+    requests = [];
+    constructor(config = {}) {
+        const merged = { ...exports.DEFAULT_RATE_LIMITER_CONFIG, ...config };
+        this.maxRequests = merged.maxRequests;
+        this.windowMs = merged.windowMs;
+        this.waitOnLimit = merged.waitOnLimit ?? false;
+        this.maxWaitMs = merged.maxWaitMs ?? 30000;
+    }
+    /**
+     * Clean up expired request timestamps
+     */
+    cleanup() {
+        const now = Date.now();
+        this.requests = this.requests.filter(timestamp => now - timestamp < this.windowMs);
+    }
+    /**
+     * Get current request count in window
+     */
+    get currentCount() {
+        this.cleanup();
+        return this.requests.length;
+    }
+    /**
+     * Get remaining requests in window
+     */
+    get remaining() {
+        return Math.max(0, this.maxRequests - this.currentCount);
+    }
+    /**
+     * Get time until window resets (oldest request expires)
+     */
+    get resetTime() {
+        if (this.requests.length === 0) {
+            return 0;
+        }
+        const oldest = Math.min(...this.requests);
+        return Math.max(0, this.windowMs - (Date.now() - oldest));
+    }
+    /**
+     * Check if a request can be made without blocking
+     */
+    canAcquire() {
+        this.cleanup();
+        return this.requests.length < this.maxRequests;
+    }
+    /**
+     * Try to acquire a request token
+     * @returns true if acquired, false if rate limited
+     */
+    tryAcquire() {
+        this.cleanup();
+        if (this.requests.length >= this.maxRequests) {
+            return false;
+        }
+        this.requests.push(Date.now());
+        return true;
+    }
+    /**
+     * Acquire a request token, throwing if rate limited
+     * @throws RateLimitError if rate limited and waitOnLimit is false
+     */
+    acquire() {
+        if (!this.tryAcquire()) {
+            const retryAfter = Math.ceil(this.resetTime / 1000);
+            throw new errors_1.RateLimitError(`Rate limit exceeded. ${this.maxRequests} requests per ${this.windowMs / 1000}s`, retryAfter);
+        }
+    }
+    /**
+     * Acquire a request token, waiting if necessary
+     * @throws RateLimitError if wait exceeds maxWaitMs
+     */
+    async acquireAsync() {
+        const startTime = Date.now();
+        while (!this.tryAcquire()) {
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= this.maxWaitMs) {
+                throw new errors_1.RateLimitError(`Rate limit wait exceeded ${this.maxWaitMs}ms`, Math.ceil((this.maxWaitMs - elapsed) / 1000));
+            }
+            // Wait for the oldest request to expire
+            const waitTime = Math.min(this.resetTime, this.maxWaitMs - elapsed, 1000);
+            if (waitTime > 0) {
+                await (0, retry_1.sleep)(waitTime);
+            }
+        }
+    }
+    /**
+     * Execute a function with rate limiting
+     */
+    async execute(fn) {
+        if (this.waitOnLimit) {
+            await this.acquireAsync();
+        }
+        else {
+            this.acquire();
+        }
+        return fn();
+    }
+    /**
+     * Reset the rate limiter
+     */
+    reset() {
+        this.requests = [];
+    }
+    /**
+     * Get rate limiter status for monitoring
+     */
+    getStatus() {
+        return {
+            currentCount: this.currentCount,
+            maxRequests: this.maxRequests,
+            remaining: this.remaining,
+            resetTime: this.resetTime,
+            windowMs: this.windowMs,
+        };
+    }
+}
+exports.RateLimiter = RateLimiter;
+/**
+ * Global rate limiter instance
+ */
+let globalRateLimiter = null;
+/**
+ * Get or create the global rate limiter
+ */
+function getRateLimiter(config) {
+    if (!globalRateLimiter) {
+        globalRateLimiter = new RateLimiter(config);
+    }
+    return globalRateLimiter;
+}
+/**
+ * Reset the global rate limiter (for testing)
+ */
+function resetGlobalRateLimiter() {
+    globalRateLimiter = null;
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/api/rate-limiter.js.map

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

package/dist/api/request-queue.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Request queue with priority and deduplication
+ */
+/**
+ * Request queue configuration
+ */
+export interface RequestQueueConfig {
+    /** Maximum concurrent requests */
+    maxConcurrent: number;
+    /** Maximum queue size */
+    maxQueueSize: number;
+    /** Request timeout in ms */
+    requestTimeout: number;
+}
+/**
+ * Default request queue configuration
+ */
+export declare const DEFAULT_REQUEST_QUEUE_CONFIG: RequestQueueConfig;
+/**
+ * Request queue with priority ordering and deduplication
+ */
+export declare class RequestQueue {
+    private readonly maxConcurrent;
+    private readonly maxQueueSize;
+    private readonly requestTimeout;
+    private queue;
+    private inFlight;
+    private processing;
+    constructor(config?: Partial<RequestQueueConfig>);
+    /**
+     * Get queue length
+     */
+    get length(): number;
+    /**
+     * Get number of in-flight requests
+     */
+    get inFlightCount(): number;
+    /**
+     * Check if queue is full
+     */
+    get isFull(): boolean;
+    /**
+     * Add a request to the queue
+     */
+    add<T>(execute: () => Promise<T>, options?: {
+        priority?: 'high' | 'normal' | 'low';
+        dedupeKey?: string;
+    }): Promise<T>;
+    /**
+     * Insert request into queue by priority
+     */
+    private enqueue;
+    /**
+     * Process queued requests
+     */
+    private processQueue;
+    /**
+     * Execute a single request with timeout
+     */
+    private executeRequest;
+    /**
+     * Clear the queue
+     */
+    clear(): void;
+    /**
+     * Get queue statistics
+     */
+    getStats(): {
+        queueLength: number;
+        inFlight: number;
+        maxConcurrent: number;
+        maxQueueSize: number;
+    };
+    /**
+     * Wait for all in-flight requests to complete
+     */
+    drain(): Promise<void>;
+}
+/**
+ * In-flight request deduplication map
+ */
+export declare class RequestDeduplicator {
+    private readonly inFlight;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    /**
+     * Execute a request with deduplication
+     */
+    execute<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get number of in-flight requests
+     */
+    get size(): number;
+    /**
+     * Clear all tracked requests
+     */
+    clear(): void;
+}
+//# sourceMappingURL=request-queue.d.ts.map

package/dist/api/request-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-queue.d.ts","sourceRoot":"","sources":["../../src/api/request-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAA;IACrB,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAI1C,CAAA;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,UAAU,CAAQ;gBAEd,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAOpD;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;OAEG;IACH,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,GAAE;QACP,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;QACpC,SAAS,CAAC,EAAE,MAAM,CAAA;KACd,GACL,OAAO,CAAC,CAAC,CAAC;IA4Bb;;OAEG;IACH,OAAO,CAAC,OAAO;IAiBf;;OAEG;YACW,YAAY;IAwB1B;;OAEG;YACW,cAAc;IAsB5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,EAAE,MAAM,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,YAAY,EAAE,MAAM,CAAA;KACrB;IASD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,OAAO,SAAM;IAIzB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAwB/D;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}