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

package/dist/matter/errorHandler.spec.js

@@ -0,0 +1,159 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { errorHandler, MatterErrorHandler } from './errorHandler.js';
+import { MatterCommissioningError, MatterDeviceError, MatterError, MatterErrorType, MatterNetworkError, MatterStorageError, } from './types.js';
+describe('matterErrorHandler', () => {
+    let consoleErrorSpy;
+    let consoleWarnSpy;
+    let consoleInfoSpy;
+    let consoleDebugSpy;
+    beforeEach(() => {
+        consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        consoleInfoSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        consoleDebugSpy = vi.spyOn(console, 'debug').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        consoleErrorSpy.mockRestore();
+        consoleWarnSpy.mockRestore();
+        consoleInfoSpy.mockRestore();
+        consoleDebugSpy.mockRestore();
+    });
+    describe('getInstance', () => {
+        it('should return a singleton instance', () => {
+            const instance1 = MatterErrorHandler.getInstance();
+            const instance2 = MatterErrorHandler.getInstance();
+            expect(instance1).toBe(instance2);
+        });
+        it('should return the exported singleton', () => {
+            expect(errorHandler).toBe(MatterErrorHandler.getInstance());
+        });
+    });
+    describe('handleError', () => {
+        it('should handle a generic error by categorizing it', async () => {
+            const error = new Error('test error');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalled();
+        });
+        it('should handle an already-typed MatterError directly', async () => {
+            const error = new MatterNetworkError('Network issue', { code: 'CONNECTION_FAILED', recoverable: true });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalled(); // Logger.warn uses console.error
+        });
+    });
+    describe('categorizeError', () => {
+        it('should categorize EADDRINUSE as port in use error', async () => {
+            const error = new Error('bind EADDRINUSE');
+            await errorHandler.handleError(error);
+            // Check that the error was logged (Logger adds timestamps and prefixes)
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('port is already in use'));
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('configure a different port'));
+        });
+        it('should categorize ECONNREFUSED as connection failed', async () => {
+            const error = new Error('connect ECONNREFUSED');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('network error'));
+        });
+        it('should categorize ETIMEDOUT as connection failed', async () => {
+            const error = new Error('connect ETIMEDOUT');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('network error'));
+        });
+        it('should categorize commissioning errors', async () => {
+            const error = new Error('commissioning failed');
+            await errorHandler.handleError(error);
+            expect(consoleInfoSpy).toHaveBeenCalledWith(expect.stringContaining('commissioning'));
+        });
+        it('should categorize pairing errors as commissioning errors', async () => {
+            const error = new Error('pairing timeout');
+            await errorHandler.handleError(error);
+            expect(consoleInfoSpy).toHaveBeenCalledWith(expect.stringContaining('commissioning'));
+        });
+        it('should categorize storage errors', async () => {
+            const error = new Error('storage read failed');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('storage error'));
+        });
+        it('should categorize ENOENT as storage error', async () => {
+            const error = new Error('ENOENT: no such file or directory');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('storage error'));
+        });
+        it('should categorize corrupted storage errors with helpful message', async () => {
+            const error = new Error('storage corrupted');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('storage error'));
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('delete the Matter storage'));
+        });
+        it('should categorize configuration errors', async () => {
+            const error = new Error('invalid config');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('configuration error'));
+        });
+        it('should categorize device sync errors based on context', async () => {
+            const error = new Error('update failed');
+            // Should not throw when handling device sync errors
+            await expect(errorHandler.handleError(error, 'device sync')).resolves.not.toThrow();
+        });
+        it('should categorize server errors based on context', async () => {
+            const error = new Error('initialization failed');
+            await errorHandler.handleError(error, 'server startup');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('server error'));
+        });
+        it('should categorize unknown errors as default', async () => {
+            const error = new Error('something unexpected');
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Matter error'));
+        });
+    });
+    describe('logError', () => {
+        it('should log network port conflict as error', async () => {
+            const error = new MatterNetworkError('Port conflict', { code: 'PORT_IN_USE', recoverable: false });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('port is already in use'));
+        });
+        it('should log other network errors as warnings', async () => {
+            const error = new MatterNetworkError('Connection timeout', { code: 'CONNECTION_FAILED', recoverable: true });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('network error'));
+        });
+        it('should log commissioning errors as info', async () => {
+            const error = new MatterCommissioningError('Pairing failed', { recoverable: false });
+            await errorHandler.handleError(error);
+            expect(consoleInfoSpy).toHaveBeenCalledWith(expect.stringContaining('commissioning'));
+        });
+        it('should log device errors as debug', async () => {
+            const error = new MatterDeviceError('Sync failed', { recoverable: true });
+            // Should not throw when handling device errors
+            await expect(errorHandler.handleError(error)).resolves.not.toThrow();
+        });
+        it('should log storage errors as warnings', async () => {
+            const error = new MatterStorageError('Read failed', { recoverable: true });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('storage error'));
+        });
+        it('should log configuration errors as errors', async () => {
+            const error = new MatterError('Invalid config', 'CONFIGURATION_ERROR', { recoverable: false, type: MatterErrorType.CONFIGURATION });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('configuration error'));
+        });
+        it('should log server errors as errors', async () => {
+            const error = new MatterError('Server failed', 'SERVER_ERROR', { recoverable: true, type: MatterErrorType.SERVER });
+            await errorHandler.handleError(error);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('server error'));
+        });
+        it('should log stack trace for non-recoverable errors in debug mode', async () => {
+            const error = new MatterError('Fatal error', 'FATAL', { recoverable: false });
+            error.stack = 'Error: Fatal error\n  at test.ts:1:1';
+            await errorHandler.handleError(error);
+            // Stack trace is logged but not with console.debug, check that error was logged
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Matter error'));
+        });
+        it('should not log stack trace for recoverable errors', async () => {
+            const error = new MatterError('Recoverable error', 'RECOVERABLE', { recoverable: true });
+            error.stack = 'Error: Recoverable error\n  at test.ts:1:1';
+            await errorHandler.handleError(error);
+            expect(consoleDebugSpy).not.toHaveBeenCalledWith(expect.stringContaining('Stack trace'));
+        });
+    });
+});
+//# sourceMappingURL=errorHandler.spec.js.map

package/dist/matter/errorHandler.spec.js.map

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

package/dist/matter/errors.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Matter Protocol Errors
+ *
+ * This module provides error classes that plugin developers can throw
+ * to send specific Matter protocol status codes to controllers.
+ *
+ * When a handler throws one of these errors, the Matter server will send
+ * the appropriate status code to the controller (e.g., Home app) instead
+ * of crashing the endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { MatterStatus } from 'homebridge'
+ *
+ * handlers: {
+ *   onOff: {
+ *     on: async () => {
+ *       if (deviceIsBusy) {
+ *         throw new MatterStatus.Busy('Device is processing another command')
+ *       }
+ *       if (requestTimedOut) {
+ *         throw new MatterStatus.Timeout('Device did not respond in time')
+ *       }
+ *       // ... control device
+ *     }
+ *   }
+ * }
+ * ```
+ */
+import { Status, StatusResponseError } from '@matter/main/types';
+/**
+ * Base class for all Matter protocol errors
+ * Plugins can throw this directly or use specific error classes below
+ */
+export declare class MatterProtocolError extends StatusResponseError {
+    constructor(message: string, code: Status, clusterCode?: number);
+}
+/**
+ * Device is busy processing another action (Status.Busy = 156)
+ *
+ * Use when the device cannot handle the request because it's processing another operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Busy('Device is currently processing another command')
+ * ```
+ */
+export declare class Busy extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Operation timed out (Status.Timeout = 148)
+ *
+ * Use when the device or operation times out.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Timeout('Device did not respond within 5 seconds')
+ * ```
+ */
+export declare class Timeout extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Value out of range or invalid (Status.ConstraintError = 135)
+ *
+ * Use when a value is out of bounds or doesn't meet constraints.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.ConstraintError('Brightness must be between 0-254')
+ * ```
+ */
+export declare class ConstraintError extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Malformed action or invalid values (Status.InvalidAction = 128)
+ *
+ * Use when the command or action is malformed or has invalid field values.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.InvalidAction('Invalid color value provided')
+ * ```
+ */
+export declare class InvalidAction extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Current operational state prevents the action (Status.InvalidInState = 203)
+ *
+ * Use when the device state prevents the requested operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.InvalidInState('Cannot unlock door while security system is armed')
+ * ```
+ */
+export declare class InvalidInState extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Generic failure (Status.Failure = 1)
+ *
+ * Use as a fallback when no specific error applies.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Failure('Device returned an error')
+ * ```
+ */
+export declare class Failure extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Insufficient resources to process the request (Status.ResourceExhausted = 137)
+ *
+ * Use when the device has insufficient resources to handle the request.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.ResourceExhausted('Maximum number of scenes reached')
+ * ```
+ */
+export declare class ResourceExhausted extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * The sender does not have sufficient permissions (Status.PermissionDenied = 15)
+ *
+ * Use when access control prevents the operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.PermissionDenied('User does not have permission to unlock')
+ * ```
+ */
+export declare class PermissionDenied extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * The requested entity was not found (Status.NotFound = 139)
+ *
+ * Use when a requested resource or entity doesn't exist.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.NotFound('Scene not found')
+ * ```
+ */
+export declare class NotFound extends MatterProtocolError {
+    constructor(message?: string);
+}
+/**
+ * Helper to check if an error is a Matter protocol error
+ */
+export declare function isMatterProtocolError(error: unknown): error is MatterProtocolError;
+/**
+ * Matter protocol status codes and error classes
+ *
+ * Use these error classes to signal specific error conditions to Matter controllers.
+ * Each error class corresponds to a Matter protocol status code.
+ */
+export declare const MatterStatus: {
+    MatterProtocolError: typeof MatterProtocolError;
+    Busy: typeof Busy;
+    Timeout: typeof Timeout;
+    ConstraintError: typeof ConstraintError;
+    InvalidAction: typeof InvalidAction;
+    InvalidInState: typeof InvalidInState;
+    Failure: typeof Failure;
+    ResourceExhausted: typeof ResourceExhausted;
+    PermissionDenied: typeof PermissionDenied;
+    NotFound: typeof NotFound;
+    isMatterProtocolError: typeof isMatterProtocolError;
+};
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/matter/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAEhE;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;gBAC9C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAGhE;AAED;;;;;;;;;GASG;AACH,qBAAa,IAAK,SAAQ,mBAAmB;gBAC/B,OAAO,SAAmB;CAGvC;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAQ,SAAQ,mBAAmB;gBAClC,OAAO,SAAwB;CAG5C;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,mBAAmB;gBAC1C,OAAO,SAAkC;CAGtD;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,mBAAmB;gBACxC,OAAO,SAA6B;CAGjD;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,mBAAmB;gBACzC,OAAO,SAA2C;CAG/D;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAQ,SAAQ,mBAAmB;gBAClC,OAAO,SAAqB;CAGzC;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,mBAAmB;gBAC5C,OAAO,SAA2B;CAG/C;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;gBAC3C,OAAO,SAAsB;CAG1C;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,mBAAmB;gBACnC,OAAO,SAAqB;CAGzC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAElF;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;CAYxB,CAAA"}

package/dist/matter/errors.js

@@ -0,0 +1,200 @@
+/**
+ * Matter Protocol Errors
+ *
+ * This module provides error classes that plugin developers can throw
+ * to send specific Matter protocol status codes to controllers.
+ *
+ * When a handler throws one of these errors, the Matter server will send
+ * the appropriate status code to the controller (e.g., Home app) instead
+ * of crashing the endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { MatterStatus } from 'homebridge'
+ *
+ * handlers: {
+ *   onOff: {
+ *     on: async () => {
+ *       if (deviceIsBusy) {
+ *         throw new MatterStatus.Busy('Device is processing another command')
+ *       }
+ *       if (requestTimedOut) {
+ *         throw new MatterStatus.Timeout('Device did not respond in time')
+ *       }
+ *       // ... control device
+ *     }
+ *   }
+ * }
+ * ```
+ */
+import { Status, StatusResponseError } from '@matter/main/types';
+/**
+ * Base class for all Matter protocol errors
+ * Plugins can throw this directly or use specific error classes below
+ */
+export class MatterProtocolError extends StatusResponseError {
+    constructor(message, code, clusterCode) {
+        super(message, code, clusterCode);
+    }
+}
+/**
+ * Device is busy processing another action (Status.Busy = 156)
+ *
+ * Use when the device cannot handle the request because it's processing another operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Busy('Device is currently processing another command')
+ * ```
+ */
+export class Busy extends MatterProtocolError {
+    constructor(message = 'Device is busy') {
+        super(message, Status.Busy);
+    }
+}
+/**
+ * Operation timed out (Status.Timeout = 148)
+ *
+ * Use when the device or operation times out.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Timeout('Device did not respond within 5 seconds')
+ * ```
+ */
+export class Timeout extends MatterProtocolError {
+    constructor(message = 'Operation timed out') {
+        super(message, Status.Timeout);
+    }
+}
+/**
+ * Value out of range or invalid (Status.ConstraintError = 135)
+ *
+ * Use when a value is out of bounds or doesn't meet constraints.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.ConstraintError('Brightness must be between 0-254')
+ * ```
+ */
+export class ConstraintError extends MatterProtocolError {
+    constructor(message = 'Value out of range or invalid') {
+        super(message, Status.ConstraintError);
+    }
+}
+/**
+ * Malformed action or invalid values (Status.InvalidAction = 128)
+ *
+ * Use when the command or action is malformed or has invalid field values.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.InvalidAction('Invalid color value provided')
+ * ```
+ */
+export class InvalidAction extends MatterProtocolError {
+    constructor(message = 'Invalid action or values') {
+        super(message, Status.InvalidAction);
+    }
+}
+/**
+ * Current operational state prevents the action (Status.InvalidInState = 203)
+ *
+ * Use when the device state prevents the requested operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.InvalidInState('Cannot unlock door while security system is armed')
+ * ```
+ */
+export class InvalidInState extends MatterProtocolError {
+    constructor(message = 'Operation not allowed in current state') {
+        super(message, Status.InvalidInState);
+    }
+}
+/**
+ * Generic failure (Status.Failure = 1)
+ *
+ * Use as a fallback when no specific error applies.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.Failure('Device returned an error')
+ * ```
+ */
+export class Failure extends MatterProtocolError {
+    constructor(message = 'Operation failed') {
+        super(message, Status.Failure);
+    }
+}
+/**
+ * Insufficient resources to process the request (Status.ResourceExhausted = 137)
+ *
+ * Use when the device has insufficient resources to handle the request.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.ResourceExhausted('Maximum number of scenes reached')
+ * ```
+ */
+export class ResourceExhausted extends MatterProtocolError {
+    constructor(message = 'Insufficient resources') {
+        super(message, Status.ResourceExhausted);
+    }
+}
+/**
+ * The sender does not have sufficient permissions (Status.PermissionDenied = 15)
+ *
+ * Use when access control prevents the operation.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.PermissionDenied('User does not have permission to unlock')
+ * ```
+ */
+export class PermissionDenied extends MatterProtocolError {
+    constructor(message = 'Permission denied') {
+        super(message, Status.UnsupportedAccess);
+    }
+}
+/**
+ * The requested entity was not found (Status.NotFound = 139)
+ *
+ * Use when a requested resource or entity doesn't exist.
+ *
+ * @example
+ * ```typescript
+ * throw new MatterStatus.NotFound('Scene not found')
+ * ```
+ */
+export class NotFound extends MatterProtocolError {
+    constructor(message = 'Entity not found') {
+        super(message, Status.NotFound);
+    }
+}
+/**
+ * Helper to check if an error is a Matter protocol error
+ */
+export function isMatterProtocolError(error) {
+    return error instanceof StatusResponseError;
+}
+/**
+ * Matter protocol status codes and error classes
+ *
+ * Use these error classes to signal specific error conditions to Matter controllers.
+ * Each error class corresponds to a Matter protocol status code.
+ */
+export const MatterStatus = {
+    MatterProtocolError,
+    Busy,
+    Timeout,
+    ConstraintError,
+    InvalidAction,
+    InvalidInState,
+    Failure,
+    ResourceExhausted,
+    PermissionDenied,
+    NotFound,
+    isMatterProtocolError,
+};
+//# sourceMappingURL=errors.js.map

package/dist/matter/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/matter/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAEhE;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,mBAAmB;IAC1D,YAAY,OAAe,EAAE,IAAY,EAAE,WAAoB;QAC7D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,CAAA;IACnC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,IAAK,SAAQ,mBAAmB;IAC3C,YAAY,OAAO,GAAG,gBAAgB;QACpC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;IAC7B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAQ,SAAQ,mBAAmB;IAC9C,YAAY,OAAO,GAAG,qBAAqB;QACzC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;IAChC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAgB,SAAQ,mBAAmB;IACtD,YAAY,OAAO,GAAG,+BAA+B;QACnD,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,eAAe,CAAC,CAAA;IACxC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAc,SAAQ,mBAAmB;IACpD,YAAY,OAAO,GAAG,0BAA0B;QAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC,CAAA;IACtC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAe,SAAQ,mBAAmB;IACrD,YAAY,OAAO,GAAG,wCAAwC;QAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC,CAAA;IACvC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAQ,SAAQ,mBAAmB;IAC9C,YAAY,OAAO,GAAG,kBAAkB;QACtC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;IAChC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAAmB;IACxD,YAAY,OAAO,GAAG,wBAAwB;QAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAC1C,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAiB,SAAQ,mBAAmB;IACvD,YAAY,OAAO,GAAG,mBAAmB;QACvC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAC1C,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAS,SAAQ,mBAAmB;IAC/C,YAAY,OAAO,GAAG,kBAAkB;QACtC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IACjC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,KAAK,YAAY,mBAAmB,CAAA;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,mBAAmB;IACnB,IAAI;IACJ,OAAO;IACP,eAAe;IACf,aAAa;IACb,cAAc;IACd,OAAO;IACP,iBAAiB;IACjB,gBAAgB;IAChB,QAAQ;IACR,qBAAqB;CACtB,CAAA"}