ive-connect/dist/core/device-interface.d.ts

A universal haptic device control library for interactive experiences

/**
 * 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",
    OSCILLATE = "oscillate",
    STROKE = "stroke"
}
/**
 * Generic device information
 */
export interface DeviceInfo {
    id: string;
    name: string;
    type: string;
    firmware?: string;
    hardware?: string;
    [key: string]: unknown;
}
/**
 * Device settings interface
 * Base interface for device-specific settings
 */
export interface DeviceSettings {
    id: string;
    name: string;
    enabled: boolean;
    [key: string]: unknown;
}
/**
 * Funscript action
 */
export interface FunscriptAction {
    at: number;
    pos: number;
}
/**
 * Funscript format
 */
export interface Funscript {
    actions: FunscriptAction[];
    inverted?: boolean;
    range?: number;
    version?: string;
    metadata?: Record<string, unknown>;
    [key: string]: unknown;
}
/**
 * Script data interface - input for loading scripts
 */
export interface ScriptData {
    type: string;
    url?: string;
    content?: Funscript;
}
/**
 * Script options interface
 */
export interface ScriptOptions {
    invertScript?: boolean;
}
/**
 * Result from loading a script to a single device
 */
export interface DeviceScriptLoadResult {
    success: boolean;
    error?: string;
}
/**
 * Result from loading a script via DeviceManager
 */
export interface ScriptLoadResult {
    /** The parsed and processed funscript content */
    funscript: Funscript | null;
    /** Whether the script was successfully fetched/parsed */
    success: boolean;
    /** Error message if fetching/parsing failed */
    error?: string;
    /** Per-device load results */
    devices: Record<string, DeviceScriptLoadResult>;
}
/**
 * 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?: unknown): 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>;
    /**
     * Prepare the device to play a script
     * The funscript content is already parsed - device just needs to prepare it
     * (e.g., upload to server for Handy, store in memory for Buttplug)
     *
     * @param funscript The parsed funscript content
     * @param options Script options (e.g., inversion already applied)
     */
    prepareScript(funscript: Funscript, options?: ScriptOptions): Promise<DeviceScriptLoadResult>;
    /**
     * 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
     * @param filter Time filter for synchronization
     */
    syncTime(timeMs: number, filter?: 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: unknown) => void): void;
    /**
     * Remove event listener
     * @param event Event name
     * @param callback Callback function
     */
    off(event: string, callback: (data: unknown) => void): void;
}