buttplug 3.2.2 → 4.0.1

package/examples/web/errors-example.js

@@ -0,0 +1,110 @@
+// Buttplug Web - Error Handling Example
+//
+// This example demonstrates the different error types in Buttplug
+// and how to handle them. This is a reference for error handling patterns.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+// All Buttplug errors inherit from ButtplugError.
+// Here's the hierarchy:
+//
+// ButtplugError (base class)
+// +-- ButtplugClientConnectorException - Connection/transport issues
+// +-- ButtplugInitError                - Client/server version mismatch
+// +-- ButtplugDeviceError              - Device communication errors
+// +-- ButtplugMessageError             - Invalid message format/content
+// +-- ButtplugPingError                - Server ping timeout
+
+function handleButtplugError(e) {
+  if (e instanceof Buttplug.ButtplugClientConnectorException) {
+    // The connector couldn't establish or maintain connection.
+    // Causes: server not running, wrong address, network issues,
+    // SSL/TLS problems, connection dropped.
+    console.log(`[Connector Error] ${e.message}`);
+    console.log("Check that the server is running and accessible.");
+  } else if (e instanceof Buttplug.ButtplugInitError) {
+    // Client and server couldn't agree on protocol version.
+    // Usually means you need to upgrade client or server.
+    console.log(`[Init/Handshake Error] ${e.message}`);
+    console.log("Client and server versions may be incompatible.");
+  } else if (e instanceof Buttplug.ButtplugDeviceError) {
+    // Something went wrong communicating with a device.
+    // Causes: device disconnected, invalid command for device,
+    // device rejected command, hardware error.
+    console.log(`[Device Error] ${e.message}`);
+    console.log("The device may have disconnected or doesn't support this command.");
+  } else if (e instanceof Buttplug.ButtplugMessageError) {
+    // The message sent was invalid.
+    // Causes: malformed message, missing required fields,
+    // invalid parameter values.
+    console.log(`[Message Error] ${e.message}`);
+    console.log("This usually indicates a bug in the client library or application.");
+  } else if (e instanceof Buttplug.ButtplugPingError) {
+    // Server didn't receive ping in time, connection terminated.
+    // The ping system ensures dead connections are detected.
+    console.log(`[Ping Error] ${e.message}`);
+    console.log("Connection was lost due to ping timeout.");
+  } else if (e instanceof Buttplug.ButtplugError) {
+    // Unknown or future error type
+    console.log(`[Buttplug Error] ${e.message}`);
+  } else if (e instanceof Error) {
+    // Non-Buttplug error
+    console.log(`[System Error] ${e.message}`);
+  } else {
+    console.log(`[Unknown Error] ${e}`);
+  }
+}
+
+async function runErrorExample() {
+  console.log("Error Handling Example");
+  console.log("======================\n");
+
+  // Example 1: Connection error (server not running on wrong port)
+  console.log("1. Attempting to connect to non-existent server...");
+  const client1 = new Buttplug.ButtplugClient("Error Example");
+  try {
+    const badConnector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:99999");
+    await client1.connect(badConnector);
+  } catch (e) {
+    handleButtplugError(e);
+  }
+
+  // Example 2: Demonstrating promise-based error handling
+  console.log("\n2. Demonstrating promise-based error handling...");
+  const client2 = new Buttplug.ButtplugClient("Promise Error Example");
+  const badConnector2 = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:99998");
+
+  // You can also catch errors using .catch() on promises
+  await client2
+    .connect(badConnector2)
+    .then(() => {
+      console.log("Connected (unexpected!)");
+    })
+    .catch((e) => {
+      console.log("Caught error using .catch():");
+      handleButtplugError(e);
+    });
+
+  // Example 3: Using try/catch with async/await
+  console.log("\n3. Using try/catch with async/await...");
+  const client3 = new Buttplug.ButtplugClient("Async Error Example");
+  const invalidConnector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://notadomain.local");
+
+  try {
+    await client3.connect(invalidConnector);
+  } catch (e) {
+    // Check for specific Buttplug error types
+    console.log(`Error: ${e}`);
+    if (e instanceof Buttplug.ButtplugError) {
+      console.log("This is a Buttplug-specific error.");
+      if (e instanceof Buttplug.ButtplugClientConnectorException) {
+        console.log("Specifically, it's a connector error.");
+      }
+    } else {
+      console.log("This is a non-Buttplug error (system/network level).");
+    }
+  }
+
+  console.log("\nError handling example complete.");
+}

package/examples/web/index.html

@@ -0,0 +1,55 @@
+<html>
+  <head>
+    <style>
+      button {
+        display: block;
+        margin-bottom: 5px;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="async-example-button">Run Async Example</button>
+    <button id="errors-example-button">Run Errors Example</button>
+    <button id="remote-connector-example-button">Run Websocket Connection Example</button>
+    <button id="device-enumeration-example-button">Run Device Enumeration Example</button>
+    <button id="device-control-example-button">Run Device Control Example</button>
+    <button id="device-info-example-button">Run Device Info Example</button>
+    <button id="logging-example-button">Run Logging Example</button>
+    <button id="ping-timeout-example-button">Run Ping Timeout Example</button>
+    <script lang="javascript" src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+    <script lang="javascript" src="async-example.js"></script>
+    <script lang="javascript" src="errors-example.js"></script>
+    <script lang="javascript" src="device-control-example.js"></script>
+    <script lang="javascript" src="device-enumeration-example.js"></script>
+    <script lang="javascript" src="device-info-example.js"></script>
+    <script lang="javascript" src="logging.js"></script>
+    <script lang="javascript" src="ping-timeout-example.js"></script>
+    <script lang="javascript" src="remote-connector-example.js"></script>
+    <script lang="javascript" defer>
+      document
+        .getElementById("async-example-button")
+        .addEventListener("click", async() => await runAsyncExample());
+      document
+        .getElementById("errors-example-button")
+        .addEventListener("click", async () => await runErrorExample());
+      document
+        .getElementById("remote-connector-example-button")
+        .addEventListener("click", async () => await runWebsocketConnectionExample());
+      document
+        .getElementById("device-enumeration-example-button")
+        .addEventListener("click", async() => await runDeviceEnumerationExample());
+      document
+        .getElementById("device-control-example-button")
+        .addEventListener("click", async () => await runDeviceControlExample());
+      document
+        .getElementById("device-info-example-button")
+        .addEventListener("click", async () => await runDeviceInfoExample());
+      document
+        .getElementById("logging-example-button")
+        .addEventListener("click", async () => await runLoggingExample());
+      document
+        .getElementById("ping-timeout-example-button")
+        .addEventListener("click", async () => await runPingTimeoutExample());
+    </script>
+  </body>
+</html>

package/examples/web/logging.js

@@ -0,0 +1,42 @@
+// Buttplug Web - Logging Example
+//
+// This example demonstrates basic connection with console logging.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+async function runLoggingExample() {
+  console.log("Logging Example - Connecting with verbose logging");
+
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:12345");
+  const client = new Buttplug.ButtplugClient("Logging Example");
+
+  // Set up all event listeners to log activity
+  client.addListener("deviceadded", (device) => {
+    console.log(`[LOG] Device added: ${device.name}`);
+  });
+
+  client.addListener("deviceremoved", (device) => {
+    console.log(`[LOG] Device removed: ${device.name}`);
+  });
+
+  client.addListener("scanningfinished", () => {
+    console.log("[LOG] Scanning finished");
+  });
+
+  client.addListener("disconnect", () => {
+    console.log("[LOG] Disconnected from server");
+  });
+
+  try {
+    console.log("[LOG] Connecting...");
+    await client.connect(connector);
+    console.log("[LOG] Connected successfully!");
+
+    // Disconnect after brief demo
+    await client.disconnect();
+    console.log("[LOG] Disconnected.");
+  } catch (ex) {
+    console.log("[LOG] Connection error:", ex);
+  }
+}

package/examples/web/ping-timeout-example.js

@@ -0,0 +1,59 @@
+// Buttplug Web - Ping Timeout Example
+//
+// This example demonstrates how to handle ping timeouts and
+// connection keepalive in Buttplug. The server uses a ping system
+// to detect dead connections.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+async function runPingTimeoutExample() {
+  console.log("Ping Timeout Example");
+  console.log("====================\n");
+
+  const client = new Buttplug.ButtplugClient("Ping Timeout Example");
+
+  // The 'disconnect' event is fired when the connection drops,
+  // including due to ping timeout.
+  client.addListener("disconnect", () => {
+    console.log("[Event] Connection lost!");
+    console.log("This could be due to:");
+    console.log("  - Server shutdown");
+    console.log("  - Network failure");
+    console.log("  - Ping timeout (client didn't respond in time)");
+  });
+
+  // Connect to server
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:12345");
+
+  try {
+    console.log("Connecting...");
+    await client.connect(connector);
+    console.log("Connected!");
+
+    // The ping system is handled automatically by the client.
+    // If the server requires ping responses and the client fails
+    // to respond in time, the connection will be terminated and
+    // a ButtplugPingError will be thrown or the disconnect event fires.
+
+    console.log("\nConnection is active. The client will automatically");
+    console.log("handle ping/pong with the server.");
+
+    console.log("\nTo test ping timeout:");
+    console.log("1. Open browser dev tools Network tab");
+    console.log("2. Enable 'Offline' mode or disconnect your network");
+    console.log("3. Wait for the disconnect event to fire");
+
+    // Keep connection open to demonstrate ping handling
+    console.log("\nConnection will stay open. Check console for disconnect event.");
+
+  } catch (e) {
+    if (e instanceof Buttplug.ButtplugPingError) {
+      console.log("Connection lost due to ping timeout:", e.message);
+    } else if (e instanceof Buttplug.ButtplugClientConnectorException) {
+      console.log("Could not connect to server:", e.message);
+    } else {
+      console.log("Error:", e);
+    }
+  }
+}

package/examples/web/remote-connector-example.js

@@ -0,0 +1,68 @@
+// Buttplug Web - Remote Websocket Connector Example
+//
+// This example demonstrates how to connect to a remote Buttplug server
+// using the websocket connector. This is the standard way to connect
+// from a browser to Intiface Central.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+const runWebsocketConnectionExample = async () => {
+  // This is the default insecure address for Intiface Central (https://intiface.com/central).
+  // You can connect to it via most browsers.
+  const address = "ws://localhost:12345";
+
+  // Create the connector with the server address
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector(address);
+  const client = new Buttplug.ButtplugClient("Websocket Connection Example");
+
+  // Set up disconnect handler before connecting
+  client.addListener("disconnect", () => {
+    console.log("Server connection lost!");
+  });
+
+  // Now we connect. If anything goes wrong here, we'll either throw:
+  //
+  // - A ButtplugClientConnectorException if there's a problem with
+  //   the connector, like the network address being wrong, server not
+  //   being up, etc.
+  // - A ButtplugInitError if there is a client/server version mismatch.
+  try {
+    console.log(`Connecting to ${address}...`);
+    await client.connect(connector);
+  } catch (ex) {
+    // If our connection failed, because the server wasn't turned on, SSL/TLS
+    // wasn't turned off, etc, we'll just print and exit here.
+    //
+    // This could also mean our client is newer than our server, and we need to
+    // upgrade the server we're connecting to.
+    console.log("Connection failed:", ex);
+    return;
+  }
+
+  // We're connected!
+  console.log("Connected!");
+  console.log("Connection will disconnect automatically in 3 seconds...");
+
+  // Demonstrate we can use the connection
+  await client.startScanning();
+  console.log("Scanning for devices...");
+
+  // Disconnect after a delay
+  setTimeout(async () => {
+    console.log("Stopping scan...");
+    await client.stopScanning();
+
+    // Show any devices that were found
+    if (client.devices.size > 0) {
+      console.log("Devices found:");
+      for (const [index, device] of client.devices) {
+        console.log(`  - ${device.name} (Index: ${index})`);
+      }
+    }
+
+    console.log("Disconnecting...");
+    await client.disconnect();
+    console.log("Disconnected.");
+  }, 3000);
+};

package/node-test.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const _1 = require(".");
+async function run() {
+    const client = new _1.ButtplugClient('Test Client');
+    await client.connect(new _1.ButtplugNodeWebsocketClientConnector('ws://127.0.0.1:12345'));
+    console.log(client.devices);
+    //console.log(client.devices.get(0)!.hasOutput(OutputType.Vibrate));
+    //console.log("Vibrating");
+    try {
+        //await client.devices.get(2)!.runOutput(DeviceOutput.Vibrate.percent(0.5));
+        console.log(await client.devices.get(1).battery());
+        await client.devices.get(1).features.get(0).runInput(_1.InputType.Pressure, _1.InputCommandType.Subscribe);
+    }
+    catch (e) {
+        console.log(e);
+    }
+    await new Promise((res, _) => setTimeout(() => res(true), 3000));
+    //await client.devices.get(1)!.features.get(0)!.runInput(InputType.Pressure, InputCommandType.Unsubscribe);
+    //console.log("stopping");
+    //console.log(await client.devices.get(1)!.features.get(0)!.runOutput(DeviceOutput.Vibrate.percent(0)));
+}
+run();
+//testInterfaces();

package/node-test.ts

@@ -1,5 +1,23 @@
-import { ButtplugClient, ButtplugNodeWebsocketClientConnector } from '.';
-
-const client = new ButtplugClient('Test Client');
-client.connect(new ButtplugNodeWebsocketClientConnector('ws://127.0.0.1:12345'));
-
+import { ButtplugClient, ButtplugNodeWebsocketClientConnector, InputCommandType, InputType, OutputType } from '.';
+import { DeviceOutput, DeviceOutputCommand } from './dist/main/src/client/ButtplugClientDeviceCommand';
+
+async function run() {
+  const client = new ButtplugClient('Test Client');
+  await client.connect(new ButtplugNodeWebsocketClientConnector('ws://127.0.0.1:12345'));
+  console.log(client.devices);
+  //console.log(client.devices.get(0)!.hasOutput(OutputType.Vibrate));
+  //console.log("Vibrating");
+  try {
+    //await client.devices.get(2)!.runOutput(DeviceOutput.Vibrate.percent(0.5));
+    console.log(await client.devices.get(1)!.battery());
+    await client.devices.get(1)!.features.get(0)!.runInput(InputType.Pressure, InputCommandType.Subscribe);
+  } catch (e) {
+    console.log(e);
+  }
+  await new Promise((res, _) => setTimeout(() => res(true), 3000));
+  //await client.devices.get(1)!.features.get(0)!.runInput(InputType.Pressure, InputCommandType.Unsubscribe);
+  //console.log("stopping");
+  //console.log(await client.devices.get(1)!.features.get(0)!.runOutput(DeviceOutput.Vibrate.percent(0)));
+}
+run();
+//testInterfaces();

package/package.json

@@ -1,87 +1,85 @@
-{
-  "name": "buttplug",
-  "version": "3.2.2",
-  "description": "Buttplug Client Implementation for Typescript/Javascript",
-  "homepage": "https://github.com/buttplugio/buttplug-js/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/buttplugio/buttplug-js.git"
-  },
-  "author": "Nonpolynomial Labs, LLC",
-  "keywords": [
-    "teledildonics",
-    "hardware"
-  ],
-  "license": "BSD-3-Clause",
-  "bugs": {
-    "url": "https://github.com/buttplugio/buttplug-js/issues"
-  },
-  "main": "./dist/main/src/index.js",
-  "types": "./dist/main/src/index.d.ts",
-  "scripts": {
-    "build": "trash dist dist-bundle && yarn build:all",
-    "build:all": "yarn build:main && yarn build:web",
-    "build:main": "tsc -p tsconfig.json",
-    "build:doc": "typedoc --options typedocconfig.js --out doc ./src/index.ts",
-    "build:web": "vite build",
-    "pretest": "yarn build:main",
-    "test": "jest tests/*",
-    "web-test": "jest web-tests/test-web-library.ts",
-    "web-test-ci": "jest --runInBand web-tests/test-web-library.ts"
-  },
-  "dependencies": {
-    "class-transformer": "^0.5.1",
-    "eventemitter3": "^5.0.1",
-    "reflect-metadata": "^0.2.1",
-    "ws": "^8.16.0"
-  },
-  "devDependencies": {
-    "@types/commander": "^2.12.2",
-    "@types/expect-puppeteer": "^5.0.6",
-    "@types/jest": "^29.5.12",
-    "@types/jest-environment-puppeteer": "^5.0.6",
-    "@types/node": "^20.11.24",
-    "@types/uuid-parse": "^1.0.2",
-    "@types/ws": "^8.5.10",
-    "@typescript-eslint/eslint-plugin": "^7.1.0",
-    "@typescript-eslint/parser": "^7.1.0",
-    "copyfiles": "^2.4.1",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.57.0",
-    "eslint-plugin-node": "^11.1.0",
-    "gts": "^5.2.0",
-    "jest": "^29.7.0",
-    "mock-socket": "^9.3.1",
-    "pkg": "^5.8.1",
-    "tmp": "^0.2.3",
-    "trash": "^8.1.1",
-    "trash-cli": "^5.0.0",
-    "ts-jest": "^29.1.2",
-    "ts-node": "^10.9.2",
-    "tslib": "^2.6.2",
-    "typedoc": "^0.25.9",
-    "typescript": "^5.3.3",
-    "vite": "^5.1.4",
-    "vite-plugin-dts": "^3.7.3",
-    "yarn": "^1.22.21"
-  },
-  "jest": {
-    "moduleFileExtensions": [
-      "ts",
-      "js",
-      "json"
-    ],
-    "transform": {
-      "^.+\\.ts$": "ts-jest"
-    },
-    "testMatch": [
-      "<rootDir>/tests/**/test-*.ts",
-      "<rootDir>/web-tests/**/test-*.ts"
-    ],
-    "coverageDirectory": "./coverage/",
-    "coverageReporters": [
-      "json"
-    ],
-    "collectCoverage": true
-  }
-}
+{
+  "name": "buttplug",
+  "version": "4.0.1",
+  "description": "Buttplug Client Implementation for Typescript/Javascript",
+  "homepage": "https://github.com/buttplugio/buttplug-js/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buttplugio/buttplug-js.git"
+  },
+  "author": "Nonpolynomial Labs, LLC",
+  "keywords": [
+    "teledildonics",
+    "hardware"
+  ],
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/buttplugio/buttplug-js/issues"
+  },
+  "main": "./dist/main/src/index.js",
+  "types": "./dist/main/src/index.d.ts",
+  "scripts": {
+    "build": "trash dist dist-bundle && yarn build:all",
+    "build:all": "yarn build:main && yarn build:web",
+    "build:main": "tsc -p tsconfig.json",
+    "build:doc": "typedoc --options typedocconfig.js --out doc ./src/index.ts",
+    "build:web": "vite build",
+    "pretest": "yarn build:main",
+    "test": "jest tests/*",
+    "web-test": "jest web-tests/test-web-library.ts",
+    "web-test-ci": "jest --runInBand web-tests/test-web-library.ts"
+  },
+  "dependencies": {
+    "eventemitter3": "^5.0.1",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/commander": "^2.12.5",
+    "@types/expect-puppeteer": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/jest-environment-puppeteer": "^5.0.6",
+    "@types/node": "^24.10.1",
+    "@types/uuid-parse": "^1.0.2",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-node": "^11.1.0",
+    "gts": "^6.0.2",
+    "jest": "^30.2.0",
+    "mock-socket": "^9.3.1",
+    "pkg": "^5.8.1",
+    "tmp": "^0.2.5",
+    "trash": "^10.0.0",
+    "trash-cli": "^7.0.0",
+    "ts-jest": "^29.4.5",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "yarn": "^1.22.22"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "ts",
+      "js",
+      "json"
+    ],
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "testMatch": [
+      "<rootDir>/tests/**/test-*.ts",
+      "<rootDir>/web-tests/**/test-*.ts"
+    ],
+    "coverageDirectory": "./coverage/",
+    "coverageReporters": [
+      "json"
+    ],
+    "collectCoverage": true
+  }
+}

package/src/client/ButtplugBrowserWebsocketClientConnector.ts

@@ -1,25 +1,25 @@
-/*!
- * Buttplug JS Source Code File - Visit https://buttplug.io for more info about
- * the project. Licensed under the BSD 3-Clause license. See LICENSE file in the
- * project root for full license information.
- *
- * @copyright Copyright (c) Nonpolynomial Labs LLC. All rights reserved.
- */
-
-'use strict';
-
-import { IButtplugClientConnector } from './IButtplugClientConnector';
-import { ButtplugMessage } from '../core/Messages';
-import { ButtplugBrowserWebsocketConnector } from '../utils/ButtplugBrowserWebsocketConnector';
-
-export class ButtplugBrowserWebsocketClientConnector
-  extends ButtplugBrowserWebsocketConnector
-  implements IButtplugClientConnector
-{
-  public send = (msg: ButtplugMessage): void => {
-    if (!this.Connected) {
-      throw new Error('ButtplugClient not connected');
-    }
-    this.sendMessage(msg);
-  };
-}
+/*!
+ * Buttplug JS Source Code File - Visit https://buttplug.io for more info about
+ * the project. Licensed under the BSD 3-Clause license. See LICENSE file in the
+ * project root for full license information.
+ *
+ * @copyright Copyright (c) Nonpolynomial Labs LLC. All rights reserved.
+ */
+
+'use strict';
+
+import { IButtplugClientConnector } from './IButtplugClientConnector';
+import { ButtplugMessage } from '../core/Messages';
+import { ButtplugBrowserWebsocketConnector } from '../utils/ButtplugBrowserWebsocketConnector';
+
+export class ButtplugBrowserWebsocketClientConnector
+  extends ButtplugBrowserWebsocketConnector
+  implements IButtplugClientConnector
+{
+  public send = (msg: ButtplugMessage): void => {
+    if (!this.Connected) {
+      throw new Error('ButtplugClient not connected');
+    }
+    this.sendMessage(msg);
+  };
+}