@eventmsg/transport-webble/dist/index.d.cts

EventMsgV3 Web Bluetooth transport for browser-based communication with ESP32 devices

import { BaseTransport, TransportConfig } from "@eventmsg/core";

//#region src/types/config.d.ts

/**
 * Web Bluetooth service configuration
 */
interface WebBLEServiceConfig {
  /**
   * Service UUID (e.g., Nordic UART Service)
   */
  uuid: string;
  /**
   * TX characteristic UUID (device → browser, notification)
   */
  txCharacteristic: string;
  /**
   * RX characteristic UUID (browser → device, write)
   */
  rxCharacteristic: string;
}
/**
 * Connection behavior configuration
 */
interface WebBLEConnectionConfig {
  /**
   * Connection timeout in milliseconds
   * @default 10_000
   */
  timeout?: number;
  /**
   * Preferred MTU size in bytes
   * @default auto-negotiate
   */
  mtu?: number;
  /**
   * Whether to cache device for reconnection
   * @default true
   */
  persistDevice?: boolean;
  /**
   * Number of automatic reconnection attempts
   * @default 3
   */
  reconnectAttempts?: number;
  /**
   * Delay between reconnection attempts in milliseconds
   * @default 1_000
   */
  reconnectDelay?: number;
}
/**
 * Configuration for WebBLE transport extending base TransportConfig
 */
interface WebBLETransportConfig extends TransportConfig {
  /**
   * BLE service configuration
   */
  service: WebBLEServiceConfig;
  /**
   * Optional device filtering for requestDevice()
   */
  filters?: BluetoothLEScanFilter[];
  /**
   * Connection behavior configuration
   */
  connection?: WebBLEConnectionConfig;
}
/**
 * Nordic UART Service preset configuration
 * Standard service used by most ESP32 BLE examples
 */
declare const NORDIC_UART_SERVICE: WebBLEServiceConfig;
/**
 * Create a WebBLE transport config with Nordic UART defaults
 */
declare function createNordicUARTConfig(localAddress: number, groupAddress: number, overrides?: Partial<WebBLETransportConfig>): WebBLETransportConfig;
//#endregion
//#region src/types/errors.d.ts
/**
 * Web Bluetooth specific error codes
 */
declare const WebBLEErrorCode: {
  /** Browser doesn't support Web Bluetooth */
  readonly NOT_SUPPORTED: "NOT_SUPPORTED";
  /** Not in secure context (HTTPS required) */
  readonly INSECURE_CONTEXT: "INSECURE_CONTEXT";
  /** User cancelled device selection */
  readonly USER_CANCELLED: "USER_CANCELLED";
  /** Device not found or not available */
  readonly DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
  /** Failed to connect to GATT server */
  readonly GATT_CONNECTION_FAILED: "GATT_CONNECTION_FAILED";
  /** Service not found on device */
  readonly SERVICE_NOT_FOUND: "SERVICE_NOT_FOUND";
  /** Characteristic not found in service */
  readonly CHARACTERISTIC_NOT_FOUND: "CHARACTERISTIC_NOT_FOUND";
  /** Failed to start notifications */
  readonly NOTIFICATION_FAILED: "NOTIFICATION_FAILED";
  /** BLE write operation failed */
  readonly WRITE_FAILED: "WRITE_FAILED";
  /** Device disconnected unexpectedly */
  readonly UNEXPECTED_DISCONNECT: "UNEXPECTED_DISCONNECT";
  /** Permission denied */
  readonly PERMISSION_DENIED: "PERMISSION_DENIED";
  /** Operation timed out */
  readonly TIMEOUT: "TIMEOUT";
};
type WebBLEErrorCode = (typeof WebBLEErrorCode)[keyof typeof WebBLEErrorCode];
/**
 * Mapping of Web Bluetooth DOMException names to WebBLE error codes
 */
declare const WEB_BLUETOOTH_ERROR_MAP: Record<string, WebBLEErrorCode>;
/**
 * User-friendly error messages with solutions
 */
declare const WEB_BLUETOOTH_ERROR_MESSAGES: Record<WebBLEErrorCode, {
  message: string;
  solution: string;
}>;
//#endregion
//#region src/webble-transport.d.ts
/**
 * WebBLE Transport for EventMsgV3 protocol
 *
 * Provides Web Bluetooth connectivity for browser-based communication
 * with ESP32 devices using BLE/GATT protocol.
 *
 * Features:
 * - Nordic UART Service support by default
 * - Automatic data chunking for BLE MTU limitations
 * - Device caching and automatic reconnection
 * - Browser compatibility checks
 * - Comprehensive error handling
 */
declare class WebBLETransport extends BaseTransport<WebBLETransportConfig, BluetoothDevice> {
  private readonly logger;
  private server;
  private service;
  private rxCharacteristic;
  private txCharacteristic;
  private mtu;
  private deviceCache;
  private receiveBuffer;
  private readonly MAX_MESSAGE_SIZE;
  private bufferTimeout?;
  constructor(config: WebBLETransportConfig);
  /**
   * Check if Web Bluetooth is supported in current browser
   * @throws {ValidationError} If Web Bluetooth is not supported
   */
  private checkBrowserSupport;
  /**
   * Validate WebBLE-specific configuration
   * @param config Configuration to validate
   * @throws {ValidationError} If configuration is invalid
   */
  protected validateConfig(config: WebBLETransportConfig): void;
  /**
   * Transport-specific connection implementation
   * Handles Web Bluetooth device selection and GATT connection
   */
  protected doConnect(): Promise<void>;
  /**
   * Transport-specific disconnection implementation
   * Cleans up BLE resources and disconnects
   */
  protected doDisconnect(): Promise<void>;
  /**
   * Transport-specific send implementation
   * Sends data via BLE characteristic with automatic chunking
   */
  protected doSend(data: Uint8Array): Promise<void>;
  /**
   * Get cached device or request new device from user
   */
  private getOrRequestDevice;
  /**
   * Request device selection from user
   */
  private requestDevice;
  /**
   * Handle incoming data from BLE characteristic
   */
  private handleIncomingData;
  /**
   * Clear receive buffer and timeout
   */
  private clearReceiveBuffer;
  /**
   * Reset buffer timeout
   */
  private resetBufferTimeout;
  /**
   * Handle GATT server disconnection event
   */
  private handleGATTDisconnect;
  /**
   * Negotiate MTU size with device
   */
  private negotiateMTU;
  /**
   * Cache device for reconnection
   */
  private cacheDevice;
  /**
   * Split data into chunks that fit within BLE MTU
   */
  private chunkData;
  /**
   * Send a single data chunk
   */
  private sendChunk;
  /**
   * Clean up BLE connection resources
   */
  private cleanupConnection;
  /**
   * Convert Web Bluetooth errors to transport errors
   */
  private wrapBLEError;
}
//#endregion
export { NORDIC_UART_SERVICE, WEB_BLUETOOTH_ERROR_MAP, WEB_BLUETOOTH_ERROR_MESSAGES, type WebBLEConnectionConfig, WebBLEErrorCode, type WebBLEServiceConfig, WebBLETransport, type WebBLETransportConfig, createNordicUARTConfig };
//# sourceMappingURL=index.d.cts.map