react-native-ble-mesh 1.0.1

package/src/errors/CryptoError.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * @fileoverview Cryptographic error class
+ * @module errors/CryptoError
+ */
+
+const MeshError = require('./MeshError');
+const { ERROR_MESSAGES } = require('../constants/errors');
+
+/**
+ * Error class for cryptographic operation failures
+ * @class CryptoError
+ * @extends MeshError
+ */
+class CryptoError extends MeshError {
+  /**
+   * Creates a new CryptoError
+   * @param {string} message - Human-readable error message
+   * @param {string} [code='E400'] - Error code (E4xx range)
+   * @param {Object|null} [details=null] - Additional error context
+   */
+  constructor(message, code = 'E400', details = null) {
+    super(message, code, details);
+    this.name = 'CryptoError';
+  }
+
+  /**
+   * Creates an error from an error code
+   * @param {string} code - Error code from ERROR_CODE constants
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static fromCode(code, details = null) {
+    const message = ERROR_MESSAGES[code] || ERROR_MESSAGES.E400;
+    return new CryptoError(message, code, details);
+  }
+
+  /**
+   * Creates a key generation error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static keyGenerationFailed(details = null) {
+    return CryptoError.fromCode('E400', details);
+  }
+
+  /**
+   * Creates an encryption error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static encryptionFailed(details = null) {
+    return CryptoError.fromCode('E401', details);
+  }
+
+  /**
+   * Creates a decryption error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static decryptionFailed(details = null) {
+    return CryptoError.fromCode('E402', details);
+  }
+
+  /**
+   * Creates an invalid key error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static invalidKey(details = null) {
+    return CryptoError.fromCode('E403', details);
+  }
+
+  /**
+   * Creates an invalid nonce error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static invalidNonce(details = null) {
+    return CryptoError.fromCode('E404', details);
+  }
+
+  /**
+   * Creates an authentication tag mismatch error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static authTagMismatch(details = null) {
+    return CryptoError.fromCode('E405', details);
+  }
+
+  /**
+   * Creates a nonce exhausted error
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {CryptoError} New CryptoError instance
+   */
+  static nonceExhausted(details = null) {
+    return CryptoError.fromCode('E406', details);
+  }
+}
+
+module.exports = CryptoError;

package/src/errors/HandshakeError.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * @fileoverview Handshake error class
+ * @module errors/HandshakeError
+ */
+
+const MeshError = require('./MeshError');
+const { ERROR_MESSAGES } = require('../constants/errors');
+
+/**
+ * Error class for Noise Protocol handshake failures
+ * @class HandshakeError
+ * @extends MeshError
+ */
+class HandshakeError extends MeshError {
+  /**
+   * Creates a new HandshakeError
+   * @param {string} message - Human-readable error message
+   * @param {string} [code='E300'] - Error code (E3xx range)
+   * @param {string|null} [peerId=null] - ID of the peer involved
+   * @param {number|null} [step=null] - Handshake step where error occurred
+   * @param {Object|null} [details=null] - Additional error context
+   */
+  constructor(message, code = 'E300', peerId = null, step = null, details = null) {
+    super(message, code, details);
+    this.name = 'HandshakeError';
+
+    /**
+     * ID of the peer involved in the handshake
+     * @type {string|null}
+     */
+    this.peerId = peerId;
+
+    /**
+     * Handshake step where the error occurred (1, 2, or 3 for XX pattern)
+     * @type {number|null}
+     */
+    this.step = step;
+  }
+
+  /**
+   * Creates an error from an error code
+   * @param {string} code - Error code from ERROR_CODE constants
+   * @param {string|null} [peerId=null] - ID of the peer involved
+   * @param {number|null} [step=null] - Handshake step where error occurred
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static fromCode(code, peerId = null, step = null, details = null) {
+    const message = ERROR_MESSAGES[code] || ERROR_MESSAGES.E300;
+    return new HandshakeError(message, code, peerId, step, details);
+  }
+
+  /**
+   * Creates a handshake failed error
+   * @param {string|null} [peerId=null] - ID of the peer
+   * @param {number|null} [step=null] - Handshake step
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static handshakeFailed(peerId = null, step = null, details = null) {
+    return HandshakeError.fromCode('E300', peerId, step, details);
+  }
+
+  /**
+   * Creates a handshake timeout error
+   * @param {string|null} [peerId=null] - ID of the peer
+   * @param {number|null} [step=null] - Handshake step
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static handshakeTimeout(peerId = null, step = null, details = null) {
+    return HandshakeError.fromCode('E301', peerId, step, details);
+  }
+
+  /**
+   * Creates an invalid handshake state error
+   * @param {string|null} [peerId=null] - ID of the peer
+   * @param {number|null} [step=null] - Handshake step
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static invalidState(peerId = null, step = null, details = null) {
+    return HandshakeError.fromCode('E302', peerId, step, details);
+  }
+
+  /**
+   * Creates a decryption failed error during handshake
+   * @param {string|null} [peerId=null] - ID of the peer
+   * @param {number|null} [step=null] - Handshake step
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static decryptionFailed(peerId = null, step = null, details = null) {
+    return HandshakeError.fromCode('E303', peerId, step, details);
+  }
+
+  /**
+   * Creates an already in progress error
+   * @param {string|null} [peerId=null] - ID of the peer
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {HandshakeError} New HandshakeError instance
+   */
+  static alreadyInProgress(peerId = null, details = null) {
+    return HandshakeError.fromCode('E304', peerId, null, details);
+  }
+
+  /**
+   * Converts error to a JSON-serializable object
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      peerId: this.peerId,
+      step: this.step
+    };
+  }
+}
+
+module.exports = HandshakeError;

package/src/errors/MeshError.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * @fileoverview Base error class for BLE Mesh Network library
+ * @module errors/MeshError
+ */
+
+const { ERROR_CODE, ERROR_MESSAGES } = require('../constants/errors');
+
+/**
+ * Base error class for all mesh-related errors
+ * @class MeshError
+ * @extends Error
+ */
+class MeshError extends Error {
+  /**
+   * Creates a new MeshError
+   * @param {string} message - Human-readable error message
+   * @param {string} [code='E900'] - Error code from ERROR_CODE constants
+   * @param {Object|null} [details=null] - Additional error context
+   */
+  constructor(message, code = 'E900', details = null) {
+    super(message);
+
+    /**
+     * Error name
+     * @type {string}
+     */
+    this.name = this.constructor.name;
+
+    /**
+     * Error code
+     * @type {string}
+     */
+    this.code = code;
+
+    /**
+     * Additional error details
+     * @type {Object|null}
+     */
+    this.details = details;
+
+    /**
+     * Timestamp when error occurred
+     * @type {number}
+     */
+    this.timestamp = Date.now();
+
+    // Capture stack trace (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Creates an error from an error code
+   * @param {string} code - Error code from ERROR_CODE constants
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MeshError} New MeshError instance
+   */
+  static fromCode(code, details = null) {
+    const message = ERROR_MESSAGES[code] || ERROR_MESSAGES.E900;
+    return new MeshError(message, code, details);
+  }
+
+  /**
+   * Gets the error type name from ERROR_CODE
+   * @returns {string} Error type name
+   */
+  getTypeName() {
+    return ERROR_CODE[this.code] || 'UNKNOWN_ERROR';
+  }
+
+  /**
+   * Converts error to a JSON-serializable object
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      typeName: this.getTypeName(),
+      details: this.details,
+      timestamp: this.timestamp,
+      stack: this.stack
+    };
+  }
+
+  /**
+   * Creates a string representation of the error
+   * @returns {string} String representation
+   */
+  toString() {
+    const typeName = this.getTypeName();
+    return `${this.name} [${this.code}:${typeName}]: ${this.message}`;
+  }
+}
+
+module.exports = MeshError;

package/src/errors/MessageError.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * @fileoverview Message error class
+ * @module errors/MessageError
+ */
+
+const MeshError = require('./MeshError');
+const { ERROR_MESSAGES } = require('../constants/errors');
+
+/**
+ * Error class for message-related failures
+ * @class MessageError
+ * @extends MeshError
+ */
+class MessageError extends MeshError {
+  /**
+   * Creates a new MessageError
+   * @param {string} message - Human-readable error message
+   * @param {string} [code='E500'] - Error code (E5xx range)
+   * @param {string|null} [messageId=null] - ID of the message involved
+   * @param {Object|null} [details=null] - Additional error context
+   */
+  constructor(message, code = 'E500', messageId = null, details = null) {
+    super(message, code, details);
+    this.name = 'MessageError';
+
+    /**
+     * ID of the message involved in the error
+     * @type {string|null}
+     */
+    this.messageId = messageId;
+  }
+
+  /**
+   * Creates an error from an error code
+   * @param {string} code - Error code from ERROR_CODE constants
+   * @param {string|null} [messageId=null] - ID of the message involved
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static fromCode(code, messageId = null, details = null) {
+    const message = ERROR_MESSAGES[code] || ERROR_MESSAGES.E500;
+    return new MessageError(message, code, messageId, details);
+  }
+
+  /**
+   * Creates a message too large error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static messageTooLarge(messageId = null, details = null) {
+    return MessageError.fromCode('E500', messageId, details);
+  }
+
+  /**
+   * Creates a message expired error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static messageExpired(messageId = null, details = null) {
+    return MessageError.fromCode('E501', messageId, details);
+  }
+
+  /**
+   * Creates an invalid format error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static invalidFormat(messageId = null, details = null) {
+    return MessageError.fromCode('E502', messageId, details);
+  }
+
+  /**
+   * Creates an invalid checksum error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static invalidChecksum(messageId = null, details = null) {
+    return MessageError.fromCode('E503', messageId, details);
+  }
+
+  /**
+   * Creates a duplicate message error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static duplicate(messageId = null, details = null) {
+    return MessageError.fromCode('E504', messageId, details);
+  }
+
+  /**
+   * Creates a max hops exceeded error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static maxHopsExceeded(messageId = null, details = null) {
+    return MessageError.fromCode('E505', messageId, details);
+  }
+
+  /**
+   * Creates a send failed error
+   * @param {string|null} [messageId=null] - ID of the message
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {MessageError} New MessageError instance
+   */
+  static sendFailed(messageId = null, details = null) {
+    return MessageError.fromCode('E506', messageId, details);
+  }
+
+  /**
+   * Converts error to a JSON-serializable object
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      messageId: this.messageId
+    };
+  }
+}
+
+module.exports = MessageError;

package/src/errors/ValidationError.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * @fileoverview Validation error class
+ * @module errors/ValidationError
+ */
+
+const MeshError = require('./MeshError');
+const { ERROR_MESSAGES } = require('../constants/errors');
+
+/**
+ * Error class for input validation failures
+ * @class ValidationError
+ * @extends MeshError
+ */
+class ValidationError extends MeshError {
+  /**
+   * Creates a new ValidationError
+   * @param {string} message - Human-readable error message
+   * @param {string} [code='E800'] - Error code (E8xx range)
+   * @param {string|null} [field=null] - Name of the field that failed validation
+   * @param {*} [value=undefined] - The invalid value
+   * @param {Object|null} [details=null] - Additional error context
+   */
+  constructor(message, code = 'E800', field = null, value = undefined, details = null) {
+    super(message, code, details);
+    this.name = 'ValidationError';
+
+    /**
+     * Name of the field that failed validation
+     * @type {string|null}
+     */
+    this.field = field;
+
+    /**
+     * The invalid value (sanitized to prevent secret exposure)
+     * @type {string|undefined}
+     */
+    this.value = value !== undefined ? ValidationError.sanitizeValue(value) : undefined;
+  }
+
+  /**
+   * Sanitizes a value for safe inclusion in error output
+   * @param {*} value - The value to sanitize
+   * @returns {string} Sanitized string representation
+   * @private
+   */
+  static sanitizeValue(value) {
+    if (value === null) { return 'null'; }
+    if (value === undefined) { return 'undefined'; }
+
+    const type = typeof value;
+
+    if (type === 'string') {
+      // Truncate long strings and mask potentially sensitive data
+      if (value.length > 50) {
+        return `"${value.substring(0, 47)}..." (${value.length} chars)`;
+      }
+      return `"${value}"`;
+    }
+
+    if (type === 'number' || type === 'boolean') {
+      return String(value);
+    }
+
+    if (value instanceof Uint8Array) {
+      return `Uint8Array(${value.length})`;
+    }
+
+    if (Array.isArray(value)) {
+      return `Array(${value.length})`;
+    }
+
+    if (type === 'object') {
+      return `Object(${Object.keys(value).length} keys)`;
+    }
+
+    return `[${type}]`;
+  }
+
+  /**
+   * Creates an error from an error code
+   * @param {string} code - Error code from ERROR_CODE constants
+   * @param {string|null} [field=null] - Name of the field
+   * @param {*} [value=undefined] - The invalid value
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {ValidationError} New ValidationError instance
+   */
+  static fromCode(code, field = null, value = undefined, details = null) {
+    const message = ERROR_MESSAGES[code] || ERROR_MESSAGES.E800;
+    return new ValidationError(message, code, field, value, details);
+  }
+
+  /**
+   * Creates an invalid argument error
+   * @param {string} field - Name of the field
+   * @param {*} [value=undefined] - The invalid value
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {ValidationError} New ValidationError instance
+   */
+  static invalidArgument(field, value = undefined, details = null) {
+    return ValidationError.fromCode('E801', field, value, details);
+  }
+
+  /**
+   * Creates a missing argument error
+   * @param {string} field - Name of the missing field
+   * @param {Object|null} [details=null] - Additional error context
+   * @returns {ValidationError} New ValidationError instance
+   */
+  static missingArgument(field, details = null) {
+    return ValidationError.fromCode('E802', field, undefined, details);
+  }
+
+  /**
+   * Creates an invalid type error
+   * @param {string} field - Name of the field
+   * @param {*} value - The invalid value
+   * @param {string} expectedType - Expected type description
+   * @returns {ValidationError} New ValidationError instance
+   */
+  static invalidType(field, value, expectedType) {
+    return ValidationError.fromCode('E803', field, value, { expectedType });
+  }
+
+  /**
+   * Creates an out of range error
+   * @param {string} field - Name of the field
+   * @param {*} value - The invalid value
+   * @param {Object} range - Expected range { min, max }
+   * @returns {ValidationError} New ValidationError instance
+   */
+  static outOfRange(field, value, range) {
+    return ValidationError.fromCode('E804', field, value, { range });
+  }
+
+  /**
+   * Converts error to a JSON-serializable object
+   * @returns {Object} JSON representation of the error
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      field: this.field,
+      value: this.value
+    };
+  }
+}
+
+module.exports = ValidationError;

package/src/errors/index.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * @fileoverview Error classes for BLE Mesh Network library
+ * @module errors
+ */
+
+const MeshError = require('./MeshError');
+const CryptoError = require('./CryptoError');
+const ConnectionError = require('./ConnectionError');
+const HandshakeError = require('./HandshakeError');
+const MessageError = require('./MessageError');
+const ValidationError = require('./ValidationError');
+const AudioError = require('./AudioError');
+
+module.exports = {
+  MeshError,
+  CryptoError,
+  ConnectionError,
+  HandshakeError,
+  MessageError,
+  ValidationError,
+  AudioError
+};