ive-connect/README.md

A universal haptic device control library for interactive experiences

# ive-connect

A universal haptic device control library that provides a consistent interface for managing various haptic devices (Handy, Buttplug, etc.).

## Features

- Unified device control interface
- Support for multiple device types
- Event-based state management
- TypeScript support

## Installation

```bash
npm install ive-connect
```

## Quick Start

```typescript
import { DeviceManager, HandyDevice } from 'ive-connect'

// Create a device manager
const manager = new DeviceManager()

// Create and register a Handy device
const handyDevice = new HandyDevice({
  connectionKey: 'your-connection-key',
})
manager.registerDevice(handyDevice)

// Connect to the device
await handyDevice.connect()

// Load a script
await handyDevice.loadScript({
  type: 'funscript',
  url: 'https://example.com/script.funscript',
})

// Start playback
await handyDevice.play(0, 1.0, false)

// Later, stop playback
await handyDevice.stop()

// Disconnect when done
await handyDevice.disconnect()
```

## Supported Devices

### Handy

```typescript
import { HandyDevice } from 'ive-connect'

const handy = new HandyDevice({
  connectionKey: 'your-connection-key',
  // Optional custom configuration
  baseV3Url: 'https://www.handyfeeling.com/api/v3',
  baseV2Url: 'https://www.handyfeeling.com/api/v2',
  applicationId: 'YourAppName',
})

// Connect to the device
await handy.connect()

// Update configuration
await handy.updateConfig({
  offset: -200, // Timing offset in milliseconds
  stroke: {
    min: 0.1, // Min stroke position (0.0 to 1.0)
    max: 0.9, // Max stroke position (0.0 to 1.0)
  },
})

// Listen for events
handy.on('connected', (deviceInfo) => {
  console.log('Connected to Handy:', deviceInfo)
})

handy.on('playbackStateChanged', (state) => {
  console.log('Playback state changed:', state.isPlaying)
})
```

### Using the Device Manager

```typescript
import { DeviceManager, HandyDevice } from 'ive-connect'

// Create a device manager
const manager = new DeviceManager()

// Register devices
const handy = new HandyDevice({
  connectionKey: 'your-connection-key',
})
manager.registerDevice(handy)
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Patreon: [iveplay](https://www.patreon.com/c/iveplay)
- Solana: `Hbmc4EDZz9Y8qbb4rhnPAvHAjJUFLgSVHPGebHqMKCc7`

## Acknowledgments

This project uses [buttplug.io](https://buttplug.io) (BSD 3-Clause License) for device communication.  
[Funscript Player](https://funscriptplayer.com/) was a great example of buttplug.io integration.