ive-connect 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# 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);
+
+// Connect all devices
+await manager.connectAll();
+
+// Load a script to all connected devices
+await manager.loadScriptAll({
+  type: "funscript",
+  url: "https://example.com/script.funscript",
+});
+
+// Start playback on all devices
+await manager.playAll(0, 1.0, false);
+
+// Sync time on all devices every second
+setInterval(() => {
+  manager.syncTimeAll(videoElement.currentTime * 1000);
+}, 1000);
+
+// Listen for events from any device
+manager.on("device:connected", ({ deviceId, data }) => {
+  console.log(`Device ${deviceId} connected:`, data);
+});
+
+// Listen for events from a specific device
+manager.on(`device:${handy.id}:error`, (error) => {
+  console.error(`Error from ${handy.id}:`, error);
+});
+```
+
+## API Reference
+
+### Core Classes
+
+#### `DeviceManager`
+
+Central manager for all haptic devices.
+
+- `registerDevice(device: HapticDevice): void` - Register a device
+- `unregisterDevice(deviceId: string): void` - Unregister a device
+- `getDevices(): HapticDevice[]` - Get all registered devices
+- `getDevice(deviceId: string): HapticDevice | undefined` - Get a specific device
+- `connectAll(): Promise<Record<string, boolean>>` - Connect all devices
+- `disconnectAll(): Promise<Record<string, boolean>>` - Disconnect all devices
+- `loadScriptAll(scriptData: ScriptData): Promise<Record<string, boolean>>` - Load script to all devices
+- `playAll(timeMs: number, playbackRate?: number, loop?: boolean): Promise<Record<string, boolean>>` - Start playback on all devices
+- `stopAll(): Promise<Record<string, boolean>>` - Stop playback on all devices
+- `syncTimeAll(timeMs: number): Promise<Record<string, boolean>>` - Sync time on all playing devices
+
+#### `HandyDevice`
+
+Implementation of the Handy device.
+
+- `connect(config?: Partial<HandySettings>): Promise<boolean>` - Connect to the device
+- `disconnect(): Promise<boolean>` - Disconnect from the device
+- `getConfig(): HandySettings` - Get current configuration
+- `updateConfig(config: Partial<HandySettings>): Promise<boolean>` - Update configuration
+- `loadScript(scriptData: ScriptData): Promise<boolean>` - Load a script
+- `play(timeMs: number, playbackRate?: number, loop?: boolean): Promise<boolean>` - Start playback
+- `stop(): Promise<boolean>` - Stop playback
+- `syncTime(timeMs: number): Promise<boolean>` - Sync time
+- `getDeviceInfo(): DeviceInfo | null` - Get device information
+
+### Events
+
+Devices and the DeviceManager emit various events that you can listen to:
+
+#### Device Events
+
+- `error` - Error occurred
+- `connected` - Device connected
+- `disconnected` - Device disconnected
+- `connectionStateChanged` - Connection state changed
+- `playbackStateChanged` - Playback state changed
+- `scriptLoaded` - Script loaded successfully
+- `configChanged` - Configuration changed
+
+#### DeviceManager Events
+
+- `deviceAdded` - Device was added to the manager
+- `deviceRemoved` - Device was removed from the manager
+- `device:{deviceId}:{eventName}` - Event from a specific device
+- `device:{eventName}` - Event from any device
+
+## Interfaces
+
+### `HapticDevice`
+
+Common interface for all haptic devices.
+
+```typescript
+interface HapticDevice {
+  readonly id: string;
+  readonly name: string;
+  readonly type: string;
+  readonly capabilities: DeviceCapability[];
+  readonly isConnected: boolean;
+  readonly isPlaying: boolean;
+
+  connect(config?: any): Promise<boolean>;
+  disconnect(): Promise<boolean>;
+  getConfig(): DeviceSettings;
+  updateConfig(config: Partial<DeviceSettings>): Promise<boolean>;
+  loadScript(scriptData: ScriptData): Promise<boolean>;
+  play(timeMs: number, playbackRate?: number, loop?: boolean): Promise<boolean>;
+  stop(): Promise<boolean>;
+  syncTime(timeMs: number): Promise<boolean>;
+  getDeviceInfo(): DeviceInfo | null;
+  on(event: string, callback: (data: any) => void): void;
+  off(event: string, callback: (data: any) => void): void;
+}
+```
+
+### `ScriptData`
+
+Data for scripts to be loaded.
+
+```typescript
+interface ScriptData {
+  type: string; // Script type (e.g., "funscript")
+  url?: string; // URL to script if remote
+  content?: any; // Script content if loaded directly
+}
+```
+
+### `DeviceSettings`
+
+Base interface for device settings.
+
+```typescript
+interface DeviceSettings {
+  id: string; // Device identifier
+  name: string; // Human-readable name
+  enabled: boolean; // Whether the device is enabled
+  [key: string]: any; // Additional device-specific settings
+}
+```
+
+### `HandySettings`
+
+Handy-specific settings.
+
+```typescript
+interface HandySettings extends DeviceSettings {
+  connectionKey: string; // Device connection key
+  offset: number; // Timing offset in milliseconds
+  stroke: {
+    min: number; // Min stroke position (0.0 to 1.0)
+    max: number; // Max stroke position (0.0 to 1.0)
+  };
+}
+```

package/dist/core/device-interface.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Core interfaces for haptic devices
+ */
+/**
+ * The connection state of a device
+ */
+export declare enum ConnectionState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected"
+}
+/**
+ * Common device capabilities
+ */
+export declare enum DeviceCapability {
+    VIBRATE = "vibrate",
+    ROTATE = "rotate",
+    LINEAR = "linear",
+    STROKE = "stroke"
+}
+/**
+ * Generic device information
+ */
+export interface DeviceInfo {
+    id: string;
+    name: string;
+    type: string;
+    firmware?: string;
+    hardware?: string;
+    [key: string]: any;
+}
+/**
+ * Device settings interface
+ * Base interface for device-specific settings
+ */
+export interface DeviceSettings {
+    id: string;
+    name: string;
+    enabled: boolean;
+    [key: string]: any;
+}
+/**
+ * Script data interface
+ */
+export interface ScriptData {
+    type: string;
+    url?: string;
+    content?: any;
+}
+/**
+ * Common interface for all haptic devices
+ */
+export interface HapticDevice {
+    /**
+     * Device information
+     */
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly capabilities: DeviceCapability[];
+    /**
+     * Connection state
+     */
+    readonly isConnected: boolean;
+    readonly isPlaying: boolean;
+    /**
+     * Connect to the device
+     * @param config Optional configuration
+     */
+    connect(config?: any): Promise<boolean>;
+    /**
+     * Disconnect from the device
+     */
+    disconnect(): Promise<boolean>;
+    /**
+     * Get current device configuration
+     */
+    getConfig(): DeviceSettings;
+    /**
+     * Update device configuration
+     * @param config Partial configuration to update
+     */
+    updateConfig(config: Partial<DeviceSettings>): Promise<boolean>;
+    /**
+     * Load a script for playback
+     * @param scriptData Script data to load
+     */
+    loadScript(scriptData: ScriptData): Promise<boolean>;
+    /**
+     * Play the loaded script at the specified time
+     * @param timeMs Current time in milliseconds
+     * @param playbackRate Playback rate (1.0 = normal speed)
+     * @param loop Whether to loop the script
+     */
+    play(timeMs: number, playbackRate?: number, loop?: boolean): Promise<boolean>;
+    /**
+     * Stop playback
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Synchronize device time with provided time
+     * @param timeMs Current time in milliseconds
+     */
+    syncTime(timeMs: number): Promise<boolean>;
+    /**
+     * Get device-specific information
+     */
+    getDeviceInfo(): DeviceInfo | null;
+    /**
+     * Add event listener
+     * @param event Event name
+     * @param callback Callback function
+     */
+    on(event: string, callback: (data: any) => void): void;
+    /**
+     * Remove event listener
+     * @param event Event name
+     * @param callback Callback function
+     */
+    off(event: string, callback: (data: any) => void): void;
+}

package/dist/core/device-interface.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Core interfaces for haptic devices
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceCapability = exports.ConnectionState = void 0;
+/**
+ * The connection state of a device
+ */
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["DISCONNECTED"] = "disconnected";
+    ConnectionState["CONNECTING"] = "connecting";
+    ConnectionState["CONNECTED"] = "connected";
+})(ConnectionState || (exports.ConnectionState = ConnectionState = {}));
+/**
+ * Common device capabilities
+ */
+var DeviceCapability;
+(function (DeviceCapability) {
+    DeviceCapability["VIBRATE"] = "vibrate";
+    DeviceCapability["ROTATE"] = "rotate";
+    DeviceCapability["LINEAR"] = "linear";
+    DeviceCapability["STROKE"] = "stroke";
+})(DeviceCapability || (exports.DeviceCapability = DeviceCapability = {}));

package/dist/core/device-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Device Manager
+ *
+ * Central manager for all haptic devices
+ */
+import { EventEmitter } from "./events";
+import { HapticDevice, ScriptData } from "./device-interface";
+/**
+ * Device Manager class
+ * Handles registration and control of multiple haptic devices
+ */
+export declare class DeviceManager extends EventEmitter {
+    private devices;
+    private scriptData;
+    /**
+     * Register a device with the manager
+     * @param device Device to register
+     */
+    registerDevice(device: HapticDevice): void;
+    /**
+     * Unregister a device from the manager
+     * @param deviceId Device ID to unregister
+     */
+    unregisterDevice(deviceId: string): void;
+    /**
+     * Get all registered devices
+     */
+    getDevices(): HapticDevice[];
+    /**
+     * Get a specific device by ID
+     * @param deviceId Device ID to retrieve
+     */
+    getDevice(deviceId: string): HapticDevice | undefined;
+    /**
+     * Connect to all registered devices
+     * @returns Object with success status for each device
+     */
+    connectAll(): Promise<Record<string, boolean>>;
+    /**
+     * Disconnect from all registered devices
+     * @returns Object with success status for each device
+     */
+    disconnectAll(): Promise<Record<string, boolean>>;
+    /**
+     * Load a script to all connected devices
+     * @param scriptData Script data to load
+     * @returns Object with success status for each device
+     */
+    loadScriptAll(scriptData: ScriptData): Promise<Record<string, boolean>>;
+    /**
+     * Start playback on all connected devices
+     * @param timeMs Current time in milliseconds
+     * @param playbackRate Playback rate (1.0 = normal speed)
+     * @param loop Whether to loop the script
+     * @returns Object with success status for each device
+     */
+    playAll(timeMs: number, playbackRate?: number, loop?: boolean): Promise<Record<string, boolean>>;
+    /**
+     * Stop playback on all connected devices
+     * @returns Object with success status for each device
+     */
+    stopAll(): Promise<Record<string, boolean>>;
+    /**
+     * Synchronize time on all connected and playing devices
+     * @param timeMs Current time in milliseconds
+     * @returns Object with success status for each device
+     */
+    syncTimeAll(timeMs: number): Promise<Record<string, boolean>>;
+    /**
+     * Set up event forwarding from a device to the manager
+     * @param device Device to forward events from
+     */
+    private setupDeviceEventForwarding;
+}

package/dist/core/device-manager.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceManager = void 0;
+/**
+ * Device Manager
+ *
+ * Central manager for all haptic devices
+ */
+const events_1 = require("./events");
+/**
+ * Device Manager class
+ * Handles registration and control of multiple haptic devices
+ */
+class DeviceManager extends events_1.EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.devices = new Map();
+        this.scriptData = null;
+    }
+    /**
+     * Register a device with the manager
+     * @param device Device to register
+     */
+    registerDevice(device) {
+        // Don't register the same device twice
+        if (this.devices.has(device.id)) {
+            return;
+        }
+        this.devices.set(device.id, device);
+        // Forward events from this device
+        this.setupDeviceEventForwarding(device);
+        // Emit device added event
+        this.emit("deviceAdded", device);
+    }
+    /**
+     * Unregister a device from the manager
+     * @param deviceId Device ID to unregister
+     */
+    unregisterDevice(deviceId) {
+        const device = this.devices.get(deviceId);
+        if (device) {
+            this.devices.delete(deviceId);
+            this.emit("deviceRemoved", device);
+        }
+    }
+    /**
+     * Get all registered devices
+     */
+    getDevices() {
+        return Array.from(this.devices.values());
+    }
+    /**
+     * Get a specific device by ID
+     * @param deviceId Device ID to retrieve
+     */
+    getDevice(deviceId) {
+        return this.devices.get(deviceId);
+    }
+    /**
+     * Connect to all registered devices
+     * @returns Object with success status for each device
+     */
+    async connectAll() {
+        const results = {};
+        for (const [id, device] of this.devices.entries()) {
+            try {
+                results[id] = await device.connect();
+            }
+            catch (error) {
+                console.error(`Error connecting device ${id}:`, error);
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Disconnect from all registered devices
+     * @returns Object with success status for each device
+     */
+    async disconnectAll() {
+        const results = {};
+        for (const [id, device] of this.devices.entries()) {
+            try {
+                results[id] = await device.disconnect();
+            }
+            catch (error) {
+                console.error(`Error disconnecting device ${id}:`, error);
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Load a script to all connected devices
+     * @param scriptData Script data to load
+     * @returns Object with success status for each device
+     */
+    async loadScriptAll(scriptData) {
+        const results = {};
+        this.scriptData = scriptData;
+        for (const [id, device] of this.devices.entries()) {
+            if (device.isConnected) {
+                try {
+                    results[id] = await device.loadScript(scriptData);
+                }
+                catch (error) {
+                    console.error(`Error loading script to device ${id}:`, error);
+                    results[id] = false;
+                }
+            }
+            else {
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Start playback on all connected devices
+     * @param timeMs Current time in milliseconds
+     * @param playbackRate Playback rate (1.0 = normal speed)
+     * @param loop Whether to loop the script
+     * @returns Object with success status for each device
+     */
+    async playAll(timeMs, playbackRate = 1.0, loop = false) {
+        const results = {};
+        for (const [id, device] of this.devices.entries()) {
+            if (device.isConnected) {
+                try {
+                    results[id] = await device.play(timeMs, playbackRate, loop);
+                }
+                catch (error) {
+                    console.error(`Error playing on device ${id}:`, error);
+                    results[id] = false;
+                }
+            }
+            else {
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Stop playback on all connected devices
+     * @returns Object with success status for each device
+     */
+    async stopAll() {
+        const results = {};
+        for (const [id, device] of this.devices.entries()) {
+            if (device.isConnected) {
+                try {
+                    results[id] = await device.stop();
+                }
+                catch (error) {
+                    console.error(`Error stopping device ${id}:`, error);
+                    results[id] = false;
+                }
+            }
+            else {
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Synchronize time on all connected and playing devices
+     * @param timeMs Current time in milliseconds
+     * @returns Object with success status for each device
+     */
+    async syncTimeAll(timeMs) {
+        const results = {};
+        for (const [id, device] of this.devices.entries()) {
+            if (device.isConnected && device.isPlaying) {
+                try {
+                    results[id] = await device.syncTime(timeMs);
+                }
+                catch (error) {
+                    console.error(`Error syncing time on device ${id}:`, error);
+                    results[id] = false;
+                }
+            }
+            else {
+                results[id] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Set up event forwarding from a device to the manager
+     * @param device Device to forward events from
+     */
+    setupDeviceEventForwarding(device) {
+        // Forward common events
+        const eventsToForward = [
+            "error",
+            "connected",
+            "disconnected",
+            "connectionStateChanged",
+            "playbackStateChanged",
+            "scriptLoaded",
+            "configChanged",
+        ];
+        for (const eventName of eventsToForward) {
+            device.on(eventName, (data) => {
+                this.emit(`device:${device.id}:${eventName}`, data);
+                // Also emit a general event for any device
+                this.emit(`device:${eventName}`, { deviceId: device.id, data });
+            });
+        }
+    }
+}
+exports.DeviceManager = DeviceManager;