buttplug 3.2.2 → 4.0.0

package/dist/web/utils/ButtplugBrowserWebsocketConnector.d.ts

@@ -1,10 +1,3 @@
-/*!
- * 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.
- */
 import { EventEmitter } from 'eventemitter3';
 import { ButtplugMessage } from '../core/Messages';
 export declare class ButtplugBrowserWebsocketConnector extends EventEmitter {

package/examples/node/SYNC_MANIFEST.md

@@ -0,0 +1,105 @@
+# Buttplug TypeScript/JavaScript Examples
+
+These examples demonstrate how to use the Buttplug TypeScript/JavaScript library for Node.js CLI applications.
+
+## Prerequisites
+
+1. Install [Intiface Central](https://intiface.com/central)
+2. Start the server in Intiface Central
+3. Install dependencies: `npm install`
+
+## Running Examples
+
+Each example can be run with ts-node:
+
+```bash
+npx ts-node --esm <example-name>.ts
+```
+
+Or use the npm scripts:
+
+```bash
+npm run connection          # Basic connection example
+npm run device-enumeration  # Device scanning and events
+npm run device-control      # Sending commands to devices
+npm run device-info         # Device feature introspection
+npm run async               # Async/await patterns
+npm run errors              # Error handling patterns
+npm run remote-connector    # Explicit connector setup
+npm run application         # Complete interactive demo
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `connection-example.ts` | Basic WebSocket connection and error handling |
+| `device-enumeration-example.ts` | Device scanning and event listening |
+| `device-control-example.ts` | Sending commands and capability queries |
+| `device-info-example.ts` | Device feature introspection |
+| `async-example.ts` | Async/await patterns and event handling |
+| `errors-example.ts` | Error type reference and handling patterns |
+| `remote-connector-example.ts` | Explicit connector setup |
+| `application-example.ts` | Complete interactive CLI demo |
+
+## Key API Patterns
+
+### Connection
+
+```typescript
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+} from 'buttplug';
+
+const client = new ButtplugClient('App Name');
+const connector = new ButtplugNodeWebsocketClientConnector('ws://127.0.0.1:12345');
+await client.connect(connector);
+```
+
+### Events
+
+```typescript
+client.addListener('deviceadded', (device) => {
+  console.log(`Device connected: ${device.name}`);
+});
+
+client.addListener('deviceremoved', (device) => {
+  console.log(`Device disconnected: ${device.name}`);
+});
+```
+
+### Device Control
+
+```typescript
+import { DeviceOutput, OutputType, InputType } from 'buttplug';
+
+// Check capabilities
+if (device.hasOutput(OutputType.Vibrate)) {
+  // Send command using the fluent builder API
+  await device.runOutput(DeviceOutput.Vibrate.percent(0.5));
+}
+
+// Stop the device
+await device.stop();
+
+// Read battery level
+if (device.hasInput(InputType.Battery)) {
+  const battery = await device.battery();
+  console.log(`Battery: ${battery * 100}%`);
+}
+```
+
+## Node.js vs Browser
+
+- **Node.js**: Use `ButtplugNodeWebsocketClientConnector` (requires `ws` package)
+- **Browser**: Use `ButtplugBrowserWebsocketClientConnector` (uses native WebSocket)
+
+## Syncing to Documentation
+
+These examples are synced to the Buttplug documentation site using the sync script in docs.buttplug.io:
+
+```bash
+cd ../docs.buttplug.io
+./scripts/sync-examples.sh
+```

package/examples/node/application-example.ts

@@ -0,0 +1,213 @@
+// Buttplug TypeScript - Complete Application Example
+//
+// This is a complete, working example that demonstrates the full workflow
+// of a Buttplug application. If you're new to Buttplug, start here!
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central (click "Start Server")
+// 3. Run: npx ts-node --esm application-example.ts
+
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+  ButtplugClientDevice,
+  ButtplugClientConnectorException,
+  ButtplugDeviceError,
+  ButtplugError,
+  DeviceOutput,
+  OutputType,
+  InputType,
+} from 'buttplug';
+import * as readline from 'readline';
+
+function createReadlineInterface(): readline.Interface {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+async function waitForEnter(prompt: string): Promise<void> {
+  const rl = createReadlineInterface();
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+async function prompt(question: string): Promise<string> {
+  const rl = createReadlineInterface();
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  console.log('===========================================');
+  console.log('  Buttplug TypeScript Application Example');
+  console.log('===========================================\n');
+
+  // Step 1: Create a client
+  // The client name identifies your application to the server.
+  const client = new ButtplugClient('My Buttplug Application');
+
+  // Step 2: Set up event handlers
+  // Always do this BEFORE connecting to avoid missing events.
+  client.addListener('deviceadded', (device: ButtplugClientDevice) => {
+    console.log(`[+] Device connected: ${device.name}`);
+  });
+
+  client.addListener('deviceremoved', (device: ButtplugClientDevice) => {
+    console.log(`[-] Device disconnected: ${device.name}`);
+  });
+
+  client.addListener('disconnect', () => {
+    console.log('[!] Server connection lost!');
+  });
+
+  // Step 3: Connect to the server
+  console.log('Connecting to Intiface Central...');
+  try {
+    const connector = new ButtplugNodeWebsocketClientConnector(
+      'ws://127.0.0.1:12345'
+    );
+    await client.connect(connector);
+  } catch (e) {
+    if (e instanceof ButtplugClientConnectorException) {
+      console.log('ERROR: Could not connect to Intiface Central!');
+      console.log(
+        'Make sure Intiface Central is running and the server is started.'
+      );
+      console.log('Default address: ws://127.0.0.1:12345');
+      return;
+    }
+    throw e;
+  }
+  console.log('Connected!\n');
+
+  // Step 4: Scan for devices
+  console.log('Scanning for devices...');
+  console.log('Turn on your Bluetooth/USB devices now.\n');
+  await client.startScanning();
+
+  // Wait for devices
+  await waitForEnter('Press Enter when your devices are connected...');
+  await client.stopScanning();
+
+  // Step 5: Check what devices we found
+  const devices = Array.from(client.devices.values());
+  if (devices.length === 0) {
+    console.log('No devices found. Make sure your device is:');
+    console.log('  - Turned on');
+    console.log('  - In pairing/discoverable mode');
+    console.log('  - Supported by Buttplug (check https://iostindex.com)');
+    await client.disconnect();
+    return;
+  }
+
+  console.log(`\nFound ${devices.length} device(s):\n`);
+
+  // Step 6: Display device capabilities
+  for (const device of devices) {
+    console.log(`  ${device.name}`);
+
+    // Check output capabilities (things we can make the device do)
+    const outputs: string[] = [];
+    if (device.hasOutput(OutputType.Vibrate)) outputs.push('Vibrate');
+    if (device.hasOutput(OutputType.Rotate)) outputs.push('Rotate');
+    if (device.hasOutput(OutputType.Oscillate)) outputs.push('Oscillate');
+    if (device.hasOutput(OutputType.Position)) outputs.push('Position');
+    if (device.hasOutput(OutputType.Constrict)) outputs.push('Constrict');
+
+    if (outputs.length > 0) {
+      console.log(`    Outputs: ${outputs.join(', ')}`);
+    }
+
+    // Check input capabilities (sensors we can read)
+    const inputs: string[] = [];
+    if (device.hasInput(InputType.Battery)) inputs.push('Battery');
+    if (device.hasInput(InputType.RSSI)) inputs.push('RSSI');
+    if (device.hasInput(InputType.Button)) inputs.push('Button');
+    if (device.hasInput(InputType.Pressure)) inputs.push('Pressure');
+
+    if (inputs.length > 0) {
+      console.log(`    Inputs: ${inputs.join(', ')}`);
+    }
+
+    console.log();
+  }
+
+  // Step 7: Interactive device control
+  console.log('=== Interactive Control ===');
+  console.log('Commands:');
+  console.log('  v <0-100>  - Vibrate all devices at percentage');
+  console.log('  s          - Stop all devices');
+  console.log('  b          - Read battery levels');
+  console.log('  q          - Quit\n');
+
+  let running = true;
+  while (running) {
+    const input = (await prompt('> ')).trim().toLowerCase();
+
+    if (!input) continue;
+
+    try {
+      if (input.startsWith('v ')) {
+        // Vibrate command
+        const percentStr = input.slice(2);
+        const percent = parseInt(percentStr, 10);
+        if (!isNaN(percent) && percent >= 0 && percent <= 100) {
+          const intensity = percent / 100.0;
+          for (const device of devices) {
+            if (device.hasOutput(OutputType.Vibrate)) {
+              await device.runOutput(DeviceOutput.Vibrate.percent(intensity));
+              console.log(`  ${device.name}: vibrating at ${percent}%`);
+            }
+          }
+        } else {
+          console.log('  Usage: v <0-100>');
+        }
+      } else if (input === 's') {
+        // Stop all devices
+        await client.stopAllDevices();
+        console.log('  All devices stopped.');
+      } else if (input === 'b') {
+        // Read battery levels
+        for (const device of devices) {
+          if (device.hasInput(InputType.Battery)) {
+            const battery = await device.battery();
+            console.log(`  ${device.name}: ${(battery * 100).toFixed(0)}% battery`);
+          } else {
+            console.log(`  ${device.name}: no battery sensor`);
+          }
+        }
+      } else if (input === 'q') {
+        running = false;
+      } else {
+        console.log('  Unknown command. Use v, s, b, or q.');
+      }
+    } catch (e) {
+      if (e instanceof ButtplugDeviceError) {
+        console.log(`  Device error: ${e.message}`);
+      } else if (e instanceof ButtplugError) {
+        console.log(`  Error: ${e.message}`);
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  // Step 8: Clean up
+  console.log('\nStopping devices and disconnecting...');
+  await client.stopAllDevices();
+  await client.disconnect();
+  console.log('Goodbye!');
+}
+
+main().catch(console.error);

package/examples/node/async-example.ts

@@ -0,0 +1,124 @@
+// Buttplug TypeScript - Async Patterns Example
+//
+// This example demonstrates async/await patterns and event handling
+// in the Buttplug library. The library is fully async - all operations
+// that might block (network, device communication) use async/await.
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central
+// 3. Run: npx ts-node --esm async-example.ts
+
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+  ButtplugClientDevice,
+  DeviceOutput,
+  OutputType,
+} from 'buttplug';
+import * as readline from 'readline';
+
+async function waitForEnter(prompt: string): Promise<void> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main(): Promise<void> {
+  const client = new ButtplugClient('Async Example');
+
+  // Events in buttplug-js use EventEmitter3.
+  // You can use addListener or on to subscribe to events.
+
+  // 'deviceadded' is fired when a new device connects
+  client.addListener('deviceadded', async (device: ButtplugClientDevice) => {
+    // Note: Event handlers can be async!
+    console.log(`[Event] Device added: ${device.name}`);
+
+    // You can interact with the device in the event handler
+    if (device.hasOutput(OutputType.Vibrate)) {
+      console.log('  Sending welcome vibration...');
+      await device.runOutput(DeviceOutput.Vibrate.percent(0.25));
+      await delay(200);
+      await device.stop();
+    }
+  });
+
+  // 'deviceremoved' is fired when a device disconnects
+  client.addListener('deviceremoved', (device: ButtplugClientDevice) => {
+    console.log(`[Event] Device removed: ${device.name}`);
+  });
+
+  // 'scanningfinished' is fired when scanning completes
+  // (some protocols scan continuously until stopped)
+  client.addListener('scanningfinished', () => {
+    console.log('[Event] Scanning finished');
+  });
+
+  // 'disconnect' is fired when the server connection drops
+  client.addListener('disconnect', () => {
+    console.log('[Event] Server disconnected!');
+  });
+
+  // 'inputreading' is fired when subscribed sensor data arrives
+  client.addListener('inputreading', (reading: unknown) => {
+    console.log(`[Event] Input reading: ${JSON.stringify(reading)}`);
+  });
+
+  // Connect asynchronously - this may take time due to network
+  console.log('Connecting to server...');
+  const connector = new ButtplugNodeWebsocketClientConnector(
+    'ws://127.0.0.1:12345'
+  );
+  await client.connect(connector);
+  console.log('Connected!\n');
+
+  // Scanning is also async - we start it and wait for events
+  console.log('Starting scan. Turn on devices now...');
+  console.log('(Events will be printed as devices connect)\n');
+  await client.startScanning();
+
+  // Wait for user input
+  await waitForEnter('Press Enter to stop scanning...');
+  await client.stopScanning();
+
+  // Demonstrate concurrent operations
+  console.log('\nDemonstrating concurrent device control...');
+  const devices = Array.from(client.devices.values());
+
+  if (devices.length > 0) {
+    // Send commands to all devices concurrently
+    const tasks = devices
+      .filter((d) => d.hasOutput(OutputType.Vibrate))
+      .map(async (device) => {
+        console.log(`  Vibrating ${device.name}...`);
+        await device.runOutput(DeviceOutput.Vibrate.percent(0.5));
+        await delay(500);
+        await device.stop();
+        console.log(`  ${device.name} stopped.`);
+      });
+
+    // Wait for all commands to complete
+    await Promise.all(tasks);
+    console.log('All devices stopped.');
+  } else {
+    console.log('No devices connected.');
+  }
+
+  await waitForEnter('\nPress Enter to disconnect...');
+  await client.disconnect();
+  console.log('Disconnected.');
+}
+
+main().catch(console.error);

package/examples/node/connection-example.ts

@@ -0,0 +1,76 @@
+// Buttplug TypeScript - Connection Example
+//
+// This example demonstrates how to connect to a Buttplug server
+// (like Intiface Central) and handle connection errors.
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central
+// 3. Run: npx ts-node --esm connection-example.ts
+
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+  ButtplugClientConnectorException,
+  ButtplugError,
+  ButtplugInitError,
+} from 'buttplug';
+import * as readline from 'readline';
+
+async function waitForEnter(prompt: string): Promise<void> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  // Create a client with your application's name.
+  // This name will be shown in Intiface Central.
+  const client = new ButtplugClient('Connection Example');
+
+  try {
+    // Create a connector to the server. Default port for Intiface Central is 12345.
+    const connector = new ButtplugNodeWebsocketClientConnector(
+      'ws://127.0.0.1:12345'
+    );
+
+    console.log('Connecting to Intiface Central...');
+    await client.connect(connector);
+
+    // We're connected!
+    console.log('Connected! Check Intiface Central for the client name.');
+    await waitForEnter('Press Enter to disconnect...');
+
+    // Disconnect cleanly
+    await client.disconnect();
+    console.log('Disconnected.');
+  } catch (e) {
+    if (e instanceof ButtplugClientConnectorException) {
+      // Connection failed - server not running, wrong address, network issues, etc.
+      console.log(`Can't connect to server: ${e.message}`);
+      console.log(
+        'Make sure Intiface Central is running and the server is started.'
+      );
+    } else if (e instanceof ButtplugInitError) {
+      // Client/server version mismatch - need to upgrade one or the other
+      console.log(`Handshake failed: ${e.message}`);
+      console.log('Client and server versions may be incompatible.');
+    } else if (e instanceof ButtplugError) {
+      // Other Buttplug-specific errors
+      console.log(`Buttplug error: ${e.message}`);
+    } else {
+      throw e;
+    }
+  }
+
+  await waitForEnter('Press Enter to exit...');
+}
+
+main().catch(console.error);

package/examples/node/device-control-example.ts

@@ -0,0 +1,131 @@
+// Buttplug TypeScript - Device Control Example
+//
+// This example demonstrates how to send commands to devices,
+// query device capabilities, and use the command builder API.
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central
+// 3. Run: npx ts-node --esm device-control-example.ts
+
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+  ButtplugClientDevice,
+  DeviceOutput,
+  OutputType,
+  InputType,
+} from 'buttplug';
+import * as readline from 'readline';
+
+async function waitForEnter(prompt: string): Promise<void> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main(): Promise<void> {
+  const client = new ButtplugClient('Device Control Example');
+
+  // Connect and scan for devices
+  const connector = new ButtplugNodeWebsocketClientConnector(
+    'ws://127.0.0.1:12345'
+  );
+
+  console.log('Connecting...');
+  await client.connect(connector);
+  console.log('Connected! Scanning for devices...');
+
+  await client.startScanning();
+  await waitForEnter('Turn on a device, then press Enter...');
+  await client.stopScanning();
+
+  // Check if we have any devices
+  if (client.devices.size === 0) {
+    console.log('No devices found. Exiting.');
+    await client.disconnect();
+    return;
+  }
+
+  // Get the first device
+  const device: ButtplugClientDevice = client.devices.values().next().value!;
+  console.log(`\nUsing device: ${device.name}`);
+
+  // Show what output types this device supports
+  console.log('\nSupported output types:');
+  for (const [index, feature] of device.features) {
+    const def = (feature as any)._feature;
+    if (def.Output) {
+      for (const outputType of Object.keys(def.Output)) {
+        console.log(
+          `  - ${outputType} (Feature ${index}: ${def.FeatureDescriptor})`
+        );
+      }
+    }
+  }
+
+  // Check for vibration support and demonstrate commands
+  if (device.hasOutput(OutputType.Vibrate)) {
+    console.log('\nDevice supports vibration.');
+
+    // Use the command builder API
+    console.log('Vibrating at 50% using command builder...');
+    await device.runOutput(DeviceOutput.Vibrate.percent(0.5));
+    await delay(1000);
+
+    console.log('Vibrating at 75%...');
+    await device.runOutput(DeviceOutput.Vibrate.percent(0.75));
+    await delay(1000);
+
+    console.log('Vibrating at 25%...');
+    await device.runOutput(DeviceOutput.Vibrate.percent(0.25));
+    await delay(1000);
+
+    // Stop the device
+    console.log('Stopping device...');
+    await device.stop();
+  } else {
+    console.log('\nDevice does not support vibration.');
+  }
+
+  // Demonstrate other output types if available
+  if (device.hasOutput(OutputType.Rotate)) {
+    console.log('\nDevice supports rotation. Rotating at 50%...');
+    await device.runOutput(DeviceOutput.Rotate.percent(0.5));
+    await delay(1000);
+    await device.stop();
+  }
+
+  if (device.hasOutput(OutputType.Position)) {
+    console.log('\nDevice supports position control. Moving to 100% over 500ms...');
+    await device.runOutput(DeviceOutput.PositionWithDuration.percent(1.0, 500));
+    await delay(1000);
+    await device.runOutput(DeviceOutput.PositionWithDuration.percent(0.0, 500));
+  }
+
+  // Try reading battery level if supported
+  if (device.hasInput(InputType.Battery)) {
+    console.log('\nReading battery level...');
+    const battery = await device.battery();
+    console.log(`Battery: ${(battery * 100).toFixed(0)}%`);
+  }
+
+  await waitForEnter('\nPress Enter to disconnect...');
+
+  // Disconnect - this automatically stops all devices
+  await client.disconnect();
+  console.log('Disconnected.');
+}
+
+main().catch(console.error);