@zendrex/buttplug.js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zendrex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @zendrex/buttplug.js
+
+TypeScript client for the [Buttplug](https://buttplug.io) protocol v4. Connect to [Intiface Central](https://intiface.com/central/), discover devices, and control them with a type-safe API.
+
+## Features
+
+- Buttplug protocol v4 over WebSocket
+- 10 output types — vibration, rotation, position, oscillation, constriction, temperature, LED, spray, and more
+- 5 sensor types — battery, RSSI, pressure, button, position (one-shot reads and subscriptions)
+- Pattern engine with 7 built-in presets, custom keyframes, and easing curves
+- Auto-reconnect with exponential backoff
+- Zod-validated protocol messages
+- Zero config — point at Intiface Central and go
+
+## Prerequisites
+
+[Intiface Central](https://intiface.com/central/) must be running on your machine or network. It manages hardware connections and exposes a WebSocket server (default `ws://127.0.0.1:12345`).
+
+## Install
+
+```bash
+bun add @zendrex/buttplug.js
+# or
+npm install @zendrex/buttplug.js
+```
+
+## Quick Start
+
+```typescript
+import { ButtplugClient, consoleLogger } from "@zendrex/buttplug.js";
+
+const client = new ButtplugClient("ws://127.0.0.1:12345", {
+  logger: consoleLogger,
+});
+
+await client.connect();
+
+client.on("deviceAdded", async ({ device }) => {
+  console.log(`Found: ${device.displayName ?? device.name}`);
+
+  if (device.canOutput("Vibrate")) {
+    await device.vibrate(0.5);
+    setTimeout(() => device.stop(), 2000);
+  }
+});
+
+await client.startScanning();
+```
+
+## API at a Glance
+
+### Client
+
+```typescript
+const client = new ButtplugClient(url, options?);
+
+await client.connect();
+await client.startScanning();
+await client.stopAll();
+await client.disconnect();
+
+client.connected;   // boolean
+client.devices;     // Device[]
+client.serverInfo;  // ServerInfo | null
+```
+
+**Events:** `connected`, `disconnected`, `reconnecting`, `reconnected`, `error`, `scanningFinished`, `deviceAdded`, `deviceRemoved`, `deviceUpdated`, `deviceList`, `inputReading`
+
+### Device
+
+All output values are normalized to `0–1`. Pass a single number for all motors or an array for per-motor control.
+
+```typescript
+await device.vibrate(0.5);
+await device.rotate(0.5, { clockwise: true });
+await device.position(0.8, { duration: 500 });
+await device.oscillate(0.7);
+await device.constrict(0.4);
+await device.stop();
+
+// Sensors
+const battery = await device.readSensor("Battery");
+const unsub = await device.subscribeSensor("RSSI", (value) => { /* ... */ });
+await unsub();
+
+// Capability checks
+device.canOutput("Vibrate");   // boolean
+device.canRead("Battery");     // boolean
+device.canSubscribe("RSSI");   // boolean
+```
+
+### Pattern Engine
+
+```typescript
+import { ButtplugClient, PatternEngine } from "@zendrex/buttplug.js";
+
+const engine = new PatternEngine(client);
+
+// Built-in preset
+const id = await engine.play(deviceIndex, "wave", {
+  intensity: 0.8,
+  speed: 1.5,
+  loop: true,
+});
+
+// Custom keyframes
+const id2 = await engine.play(deviceIndex, [
+  {
+    featureIndex: 0,
+    keyframes: [
+      { value: 0, duration: 0 },
+      { value: 1, duration: 1000, easing: "easeIn" },
+      { value: 0.2, duration: 500, easing: "easeOut" },
+    ],
+  },
+], { loop: 3, intensity: 0.6 });
+
+await engine.stop(id);
+engine.stopAll();
+engine.dispose();
+```
+
+**Presets:** `pulse`, `wave`, `ramp_up`, `ramp_down`, `heartbeat`, `surge`, `stroke`
+
+**Easings:** `linear`, `easeIn`, `easeOut`, `easeInOut`, `step`
+
+### Error Handling
+
+All errors extend `ButtplugError`:
+
+| Error | Context |
+|---|---|
+| `ConnectionError` | WebSocket/transport failure |
+| `HandshakeError` | Server rejected handshake |
+| `ProtocolError` | Server protocol error (has `.code`) |
+| `DeviceError` | Device operation failed (has `.deviceIndex`) |
+| `TimeoutError` | Operation timed out (has `.operation`, `.timeoutMs`) |
+
+### Auto-Reconnect
+
+```typescript
+const client = new ButtplugClient("ws://127.0.0.1:12345", {
+  autoReconnect: true,
+  reconnectDelay: 1000,       // initial delay
+  maxReconnectDelay: 30000,   // backoff cap
+  maxReconnectAttempts: 10,
+});
+```
+
+On reconnection, the client re-handshakes, reconciles the device list, and emits `reconnected`. The pattern engine automatically stops patterns for removed devices.
+
+## Documentation
+
+Full API reference and guides are available in the [`docs/`](./docs) directory. To run locally:
+
+```bash
+cd docs && bun run dev
+```
+
+## License
+
+[MIT](./LICENSE)