@hangtime/grip-connect 0.5.8 → 0.5.10

package/dist/interfaces/device.interface.d.ts

@@ -62,18 +62,55 @@ export interface IDevice extends IBase {
      * @readonly
      */
     commands: Commands;
+    /**
+     * Sets the callback function to be called when the activity status changes,
+     * and optionally sets the configuration for threshold and duration.
+     *
+     * This function allows you to specify a callback that will be invoked whenever
+     * the activity status changes, indicating whether the device is currently active.
+     * It also allows optionally configuring the threshold and duration used to determine activity.
+     *
+     * @param {ActiveCallback} callback - The callback function to be set. This function
+     *                                      receives a boolean value indicating the new activity status.
+     * @param {object} [options] - Optional configuration object containing the threshold and duration.
+     * @param {number} [options.threshold=2.5] - The threshold value for determining activity.
+     * @param {number} [options.duration=1000] - The duration (in milliseconds) to monitor the input for activity.
+     * @returns {void}
+     * @public
+     *
+     * @example
+     * device.active((isActive) => {
+     *   console.log(`Device is ${isActive ? 'active' : 'inactive'}`);
+     * }, { threshold: 3.0, duration: 1500 });
+     */
+    active(callback?: (data: boolean) => void, options?: {
+        threshold?: number;
+        duration?: number;
+    }): void;
     /**
      * Connects to a Bluetooth device.
      * @param {Function} [onSuccess] - Optional callback function to execute on successful connection. Default logs success.
      * @param {Function} [onError] - Optional callback function to execute on error. Default logs the error.
      * @public
+     *
+     * @example
+     * device.connect(
+     *   () => console.log("Connected successfully"),
+     *   (error) => console.error("Connection failed:", error)
+     * );
      */
     connect(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>;
     /**
      * Disconnects the device if it is currently connected.
-     * - Checks if the device is connected via it's GATT server.
-     * - If the device is connected, it attempts to gracefully disconnect.
+     * - Removes all notification listeners from the device's characteristics.
+     * - Removes the 'gattserverdisconnected' event listener.
+     * - Attempts to gracefully disconnect the device's GATT server.
+     * - Resets relevant properties to their initial states.
+     * @returns {void}
      * @public
+     *
+     * @example
+     * device.disconnect();
      */
     disconnect(): void;
     /**
@@ -85,12 +122,22 @@ export interface IDevice extends IBase {
      *
      * @returns {void} Initiates a download of the data in the specified format.
      * @private
+     *
+     * @example
+     * device.download('json');
      */
     download(format?: "csv" | "json" | "xml"): void;
     /**
      * Checks if a Bluetooth device is connected.
      * @returns {boolean} A boolean indicating whether the device is connected.
      * @public
+     *
+     * @example
+     * if (device.isConnected()) {
+     *   console.log('Device is connected');
+     * } else {
+     *   console.log('Device is not connected');
+     * }
      */
     isConnected(): boolean;
     /**
@@ -98,6 +145,11 @@ export interface IDevice extends IBase {
      * @param {NotifyCallback} callback - The callback function to be set.
      * @returns {void}
      * @public
+     *
+     * @example
+     * device.notify((data) => {
+     *   console.log('Received notification:', data);
+     * });
      */
     notify(callback: (data: massObject) => void): void;
     /**
@@ -107,14 +159,27 @@ export interface IDevice extends IBase {
      * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
      * @returns {Promise<string | undefined>} A promise that resolves when the read operation is completed.
      * @public
+     *
+     * @example
+     * const value = await device.read('battery', 'level', 1000);
+     * console.log('Battery level:', value);
      */
     read(serviceId: string, characteristicId: string, duration?: number): Promise<string | undefined>;
     /**
      * Initiates the tare calibration process.
      * @param {number} duration - The duration time for tare calibration.
-     * @returns {void}
+     * @returns {boolean} A boolean indicating whether the tare calibration was successful.
+     * @public
+     *
+     * @example
+     * const success = device.tare(5000);
+     * if (success) {
+     *   console.log('Tare calibration started');
+     * } else {
+     *   console.log('Tare calibration failed to start');
+     * }
      */
-    tare(duration?: number): void;
+    tare(duration?: number): boolean;
     /**
      * Writes a message to the specified characteristic of a Bluetooth device and optionally provides a callback to handle responses.
      * @param {string} serviceId - The service UUID of the Bluetooth device containing the target characteristic.

package/dist/models/base.model.js

@@ -3,7 +3,7 @@ export class BaseModel {
     createdAt;
     updatedAt;
     constructor(base) {
-        this.id = base.id ? base.id : self.crypto.randomUUID();
+        this.id = base.id ?? globalThis.crypto?.randomUUID();
         this.createdAt = base.createdAt;
         this.updatedAt = base.updatedAt;
     }

package/dist/models/device/entralpi.model.d.ts

@@ -22,9 +22,9 @@ export declare class Entralpi extends Device implements IEntralpi {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications: (event: Event) => void;
+    handleNotifications: (characteristic: BluetoothRemoteGATTCharacteristic) => void;
     /**
      * Retrieves hardware version from the device.
      * @returns {Promise<string>} A Promise that resolves with the hardware version.

package/dist/models/device/entralpi.model.js

@@ -147,12 +147,13 @@ export class Entralpi extends Device {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications = (event) => {
-        const characteristic = event.target;
+    handleNotifications = (characteristic) => {
         const value = characteristic.value;
         if (value) {
+            // Update timestamp
+            this.updateTimestamp();
             if (value.buffer) {
                 const receivedTime = Date.now();
                 const receivedData = (value.getUint16(0) / 100).toFixed(1);

package/dist/models/device/forceboard.model.d.ts

@@ -15,9 +15,9 @@ export declare class ForceBoard extends Device implements IForceBoard {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications: (event: Event) => void;
+    handleNotifications: (characteristic: BluetoothRemoteGATTCharacteristic) => void;
     /**
      * Retrieves humidity level from the device.
      * @returns {Promise<string>} A Promise that resolves with the humidity level,

package/dist/models/device/forceboard.model.js

@@ -176,12 +176,13 @@ export class ForceBoard extends Device {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications = (event) => {
-        const characteristic = event.target;
+    handleNotifications = (characteristic) => {
         const value = characteristic.value;
         if (value) {
+            // Update timestamp
+            this.updateTimestamp();
             if (value.buffer) {
                 const receivedTime = Date.now();
                 const dataArray = new Uint8Array(value.buffer);

package/dist/models/device/motherboard.model.d.ts

@@ -60,9 +60,9 @@ export declare class Motherboard extends Device implements IMotherboard {
      * to extract samples, calibrate masses, and update running averages of mass data.
      * If the received data is not a valid hex packet, it returns the unprocessed data.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications: (event: Event) => void;
+    handleNotifications: (characteristic: BluetoothRemoteGATTCharacteristic) => void;
     /**
      * Retrieves hardware version from the device.
      * @returns {Promise<string>} A Promise that resolves with the hardware version,

package/dist/models/device/motherboard.model.js

@@ -186,12 +186,13 @@ export class Motherboard extends Device {
      * to extract samples, calibrate masses, and update running averages of mass data.
      * If the received data is not a valid hex packet, it returns the unprocessed data.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications = (event) => {
-        const characteristic = event.target;
+    handleNotifications = (characteristic) => {
         const value = characteristic.value;
         if (value) {
+            // Update timestamp
+            this.updateTimestamp();
             if (value.buffer) {
                 for (let i = 0; i < value.byteLength; i++) {
                     this.receiveBuffer.push(value.getUint8(i));

package/dist/models/device/progressor.model.d.ts

@@ -20,9 +20,9 @@ export declare class Progressor extends Device implements IProgressor {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications: (event: Event) => void;
+    handleNotifications: (characteristic: BluetoothRemoteGATTCharacteristic) => void;
     /**
      * Stops the data stream on the specified device.
      * @returns {Promise<void>} A promise that resolves when the stream is stopped.

package/dist/models/device/progressor.model.js

@@ -111,12 +111,13 @@ export class Progressor extends Device {
      * and updates mass data including maximum and average values.
      * It also handles command responses for retrieving device information.
      *
-     * @param {Event} event - The notification event.
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
      */
-    handleNotifications = (event) => {
-        const characteristic = event.target;
+    handleNotifications = (characteristic) => {
         const value = characteristic.value;
         if (value) {
+            // Update timestamp
+            this.updateTimestamp();
             if (value.buffer) {
                 const receivedTime = Date.now();
                 // Read the first byte of the buffer to determine the kind of message

package/dist/models/device/wh-c06.model.js

@@ -72,6 +72,8 @@ export class WHC06 extends Device {
             if (!this.bluetooth.gatt) {
                 throw new Error("GATT is not available on this device");
             }
+            // Update timestamp
+            this.updateTimestamp();
             // Device has no services / characteristics, so we directly call onSuccess
             onSuccess();
             this.bluetooth.addEventListener("advertisementreceived", (event) => {

package/dist/models/device.model.d.ts

@@ -138,6 +138,22 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @protected
      */
     protected activeCallback: ActiveCallback;
+    /**
+     * Event listener for handling the 'gattserverdisconnected' event.
+     * This listener delegates the event to the `onDisconnected` method.
+     *
+     * @private
+     * @type {(event: Event) => void}
+     */
+    private onDisconnectedListener;
+    /**
+     * A map that stores notification event listeners keyed by characteristic UUIDs.
+     * This allows for proper addition and removal of event listeners associated with each characteristic.
+     *
+     * @private
+     * @type {Map<string, EventListener>}
+     */
+    private notificationListeners;
     constructor(device: Partial<IDevice>);
     /**
      * Sets the callback function to be called when the activity status changes,
@@ -154,6 +170,11 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @param {number} [options.duration=1000] - The duration (in milliseconds) to monitor the input for activity.
      * @returns {void}
      * @public
+     *
+     * @example
+     * device.active((isActive) => {
+     *   console.log(`Device is ${isActive ? 'active' : 'inactive'}`);
+     * }, { threshold: 3.0, duration: 1500 });
      */
     active: (callback: ActiveCallback, options?: {
         threshold?: number;
@@ -168,6 +189,9 @@ export declare abstract class Device extends BaseModel implements IDevice {
      *
      * @param {number} input - The dynamic value to check for activity status.
      * @returns {Promise<void>} A promise that resolves once the activity check is complete.
+     *
+     * @example
+     * await device.activityCheck(5.0);
      */
     protected activityCheck: (input: number) => Promise<void>;
     /**
@@ -175,31 +199,55 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @param {Function} [onSuccess] - Optional callback function to execute on successful connection. Default logs success.
      * @param {Function} [onError] - Optional callback function to execute on error. Default logs the error.
      * @public
+     *
+     * @example
+     * device.connect(
+     *   () => console.log("Connected successfully"),
+     *   (error) => console.error("Connection failed:", error)
+     * );
      */
     connect: (onSuccess?: () => void, onError?: (error: Error) => void) => Promise<void>;
     /**
      * Disconnects the device if it is currently connected.
-     * - Checks if the device is connected via it's GATT server.
-     * - If the device is connected, it attempts to gracefully disconnect.
+     * - Removes all notification listeners from the device's characteristics.
+     * - Removes the 'gattserverdisconnected' event listener.
+     * - Attempts to gracefully disconnect the device's GATT server.
+     * - Resets relevant properties to their initial states.
+     * @returns {void}
      * @public
+     *
+     * @example
+     * device.disconnect();
      */
     disconnect: () => void;
     /**
      * Converts the `downloadPackets` array into a CSV formatted string.
      * @returns {string} A CSV string representation of the `downloadPackets` data, with each packet on a new line.
      * @private
+     *
+     * @example
+     * const csvData = device.downloadToCSV();
+     * console.log(csvData);
      */
     private downloadToCSV;
     /**
      * Converts an array of DownloadPacket objects to a JSON string.
      * @returns {string} JSON string representation of the data.
      * @private
+     *
+     * @example
+     * const jsonData = device.downloadToJSON();
+     * console.log(jsonData);
      */
     private downloadToJSON;
     /**
      * Converts an array of DownloadPacket objects to an XML string.
      * @returns {string}  XML string representation of the data.
      * @private
+     *
+     * @example
+     * const xmlData = device.downloadToXML();
+     * console.log(xmlData);
      */
     private downloadToXML;
     /**
@@ -211,12 +259,19 @@ export declare abstract class Device extends BaseModel implements IDevice {
      *
      * @returns {void} Initiates a download of the data in the specified format.
      * @private
+     *
+     * @example
+     * device.download('json');
      */
     download: (format?: "csv" | "json" | "xml") => void;
     /**
      * Returns UUIDs of all services associated with the device.
      * @returns {string[]} Array of service UUIDs.
      * @protected
+     *
+     * @example
+     * const serviceUUIDs = device.getAllServiceUUIDs();
+     * console.log(serviceUUIDs);
      */
     protected getAllServiceUUIDs: () => string[];
     /**
@@ -225,18 +280,33 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @param {string} characteristicId - The UUID of the characteristic.
      * @returns {BluetoothRemoteGATTCharacteristic | undefined} The characteristic, if found.
      * @protected
+     *
+     * @example
+     * const characteristic = device.getCharacteristic('battery', 'level');
+     * if (characteristic) {
+     *   console.log('Characteristic found');
+     * }
      */
     protected getCharacteristic: (serviceId: string, characteristicId: string) => BluetoothRemoteGATTCharacteristic | undefined;
     /**
      * Handles notifications received from a characteristic.
-     * @param {Event} event - The notification event.
-     * @protected
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
+     *
+     * @example
+     * device.handleNotifications(someCharacteristic);
      */
-    protected handleNotifications: (event: Event) => void;
+    protected handleNotifications: (characteristic: BluetoothRemoteGATTCharacteristic) => void;
     /**
      * Checks if a Bluetooth device is connected.
      * @returns {boolean} A boolean indicating whether the device is connected.
      * @public
+     *
+     * @example
+     * if (device.isConnected()) {
+     *   console.log('Device is connected');
+     * } else {
+     *   console.log('Device is not connected');
+     * }
      */
     isConnected: () => boolean;
     /**
@@ -244,18 +314,31 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @param {NotifyCallback} callback - The callback function to be set.
      * @returns {void}
      * @public
+     *
+     * @example
+     * device.notify((data) => {
+     *   console.log('Received notification:', data);
+     * });
      */
     notify: (callback: NotifyCallback) => void;
     /**
      * Handles the 'connected' event.
      * @param {Function} onSuccess - Callback function to execute on successful connection.
      * @public
+     *
+     * @example
+     * device.onConnected(() => {
+     *   console.log('Device connected successfully');
+     * });
      */
     protected onConnected: (onSuccess: () => void) => Promise<void>;
     /**
      * Handles the 'disconnected' event.
      * @param {Event} event - The 'disconnected' event.
      * @public
+     *
+     * @example
+     * device.onDisconnected(event);
      */
     protected onDisconnected: (event: Event) => void;
     /**
@@ -265,22 +348,48 @@ export declare abstract class Device extends BaseModel implements IDevice {
      * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
      * @returns {Promise<string | undefined>} A promise that resolves when the read operation is completed.
      * @public
+     *
+     * @example
+     * const value = await device.read('battery', 'level', 1000);
+     * console.log('Battery level:', value);
      */
     read: (serviceId: string, characteristicId: string, duration?: number) => Promise<string | undefined>;
     /**
      * Initiates the tare calibration process.
      * @param {number} duration - The duration time for tare calibration.
-     * @returns {void}
+     * @returns {boolean} A boolean indicating whether the tare calibration was successful.
      * @public
+     *
+     * @example
+     * const success = device.tare(5000);
+     * if (success) {
+     *   console.log('Tare calibration started');
+     * } else {
+     *   console.log('Tare calibration failed to start');
+     * }
      */
-    tare(duration?: number): void;
+    tare(duration?: number): boolean;
     /**
      * Apply tare calibration to the provided sample.
      * @param {number} sample - The sample to calibrate.
      * @returns {number} The calibrated tare value.
      * @protected
+     *
+     * @example
+     * const calibratedSample = device.applyTare(rawSample);
+     * console.log('Calibrated sample:', calibratedSample);
      */
     protected applyTare(sample: number): number;
+    /**
+     * Updates the timestamp of the last device interaction.
+     * This method sets the updatedAt property to the current date and time.
+     * @protected
+     *
+     * @example
+     * device.updateTimestamp();
+     * console.log('Last updated:', device.updatedAt);
+     */
+    protected updateTimestamp: () => void;
     /**
      * Writes a message to the specified characteristic of a Bluetooth device and optionally provides a callback to handle responses.
      * @param {string} serviceId - The service UUID of the Bluetooth device containing the target characteristic.