ive-connect/dist/devices/handy/handy-api.d.ts

A universal haptic device control library for interactive experiences

/**
 * Handy API Implementation
 *
 * Based on the official Handy API v3
 */
import { HandyDeviceInfo, HandyTimeInfo, HspState, HspPoint, HspAddRequest, StrokeSettings } from "./types";
export declare class HandyApi {
    private readonly baseV3Url;
    private readonly baseV2Url;
    private readonly applicationId;
    private connectionKey;
    private serverTimeOffset;
    private _eventSource;
    constructor(baseV3Url: string, baseV2Url: string, applicationId: string, connectionKey?: string);
    /**
     * Set the connection key for API requests
     */
    setConnectionKey(connectionKey: string): void;
    /**
     * Get the connection key
     */
    getConnectionKey(): string;
    /**
     * Set the server time offset for synchronization
     */
    setServerTimeOffset(offset: number): void;
    /**
     * Get the server time offset
     */
    getServerTimeOffset(): number;
    /**
     * Estimate the current server time based on local time and offset
     */
    estimateServerTime(): number;
    /**
     * Get headers for API requests
     */
    private getHeaders;
    /**
     * Make an API request with error handling
     */
    private request;
    /**
     * Check if the device is connected
     */
    isConnected(): Promise<boolean>;
    /**
     * Get device information
     */
    getDeviceInfo(): Promise<HandyDeviceInfo | null>;
    /**
     * Get the current device mode
     */
    getMode(): Promise<number | null>;
    /**
     * Upload a script file to the hosting service
     * Returns the URL where the script can be accessed
     */
    uploadScript(scriptFile: File | Blob): Promise<string | null>;
    /**
     * Setup script for HSSP playback
     */
    setupScript(scriptUrl: string): Promise<boolean>;
    /**
     * Start playback with the HSSP protocol
     */
    play(videoTime: number, playbackRate?: number, loop?: boolean): Promise<HspState | null>;
    /**
     * Stop HSSP playback
     */
    stop(): Promise<HspState | null>;
    /**
     * Synchronize the device's time with video time (HSSP)
     */
    syncVideoTime(videoTime: number, filter?: number): Promise<boolean>;
    /**
     * Setup a new HSP session on the device.
     * This clears any existing HSP session state.
     * @param streamId Optional session identifier. If not provided, one will be generated.
     */
    hspSetup(streamId?: number): Promise<HspState | null>;
    /**
     * Get the current HSP state
     */
    hspGetState(): Promise<HspState | null>;
    /**
     * Add points to the HSP buffer.
     * You can add up to 100 points in a single command.
     * @param points Array of points to add (max 100)
     * @param tailPointStreamIndex The index of the last point relative to the overall stream
     * @param flush If true, clears buffer before adding new points
     * @param tailPointThreshold Optional threshold for starving notifications
     */
    hspAddPoints(points: HspPoint[], tailPointStreamIndex: number, flush?: boolean, tailPointThreshold?: number): Promise<HspState | null>;
    /**
     * Start HSP playback
     * @param startTime The start time in milliseconds
     * @param options Optional playback options
     */
    hspPlay(startTime: number, options?: {
        serverTime?: number;
        playbackRate?: number;
        pauseOnStarving?: boolean;
        loop?: boolean;
        addPoints?: HspAddRequest;
    }): Promise<HspState | null>;
    /**
     * Stop HSP playback
     */
    hspStop(): Promise<HspState | null>;
    /**
     * Pause HSP playback
     */
    hspPause(): Promise<HspState | null>;
    /**
     * Resume HSP playback
     * @param pickUp If true, resumes from current 'live' position. If false, resumes from paused position.
     */
    hspResume(pickUp?: boolean): Promise<HspState | null>;
    /**
     * Flush the HSP buffer (remove all points)
     */
    hspFlush(): Promise<HspState | null>;
    /**
     * Set the HSP loop flag
     */
    hspSetLoop(loop: boolean): Promise<HspState | null>;
    /**
     * Set the HSP playback rate
     */
    hspSetPlaybackRate(playbackRate: number): Promise<HspState | null>;
    /**
     * Set the HSP tail point stream index threshold
     */
    hspSetThreshold(threshold: number): Promise<HspState | null>;
    /**
     * Set the HSP pause-on-starving flag
     */
    hspSetPauseOnStarving(pauseOnStarving: boolean): Promise<HspState | null>;
    /**
     * Sync HSP time with external source
     * @param currentTime Current time from external source
     * @param filter Filter value for gradual adjustment (0-1)
     */
    hspSyncTime(currentTime: number, filter?: number): Promise<HspState | null>;
    /**
     * Get the current time offset
     */
    getOffset(): Promise<number>;
    /**
     * Set the time offset
     */
    setOffset(offset: number): Promise<boolean>;
    /**
     * Get device time info
     */
    getDeviceTimeInfo(): Promise<HandyTimeInfo | null>;
    /**
     * Trigger a server-device clock synchronization
     */
    clockSync(synchronous?: boolean): Promise<HandyTimeInfo | null>;
    /**
     * Get the current stroke settings
     */
    getStrokeSettings(): Promise<StrokeSettings | null>;
    /**
     * Set the stroke settings
     */
    setStrokeSettings(settings: {
        min: number;
        max: number;
    }): Promise<StrokeSettings | null>;
    /**
     * Get the server time for synchronization calculations
     */
    getServerTime(): Promise<number | null>;
    /**
     * Synchronize time with the server
     * Returns calculated server time offset
     */
    syncServerTime(sampleCount?: number): Promise<number>;
    /**
     * Create an EventSource for server-sent events
     */
    createEventSource(): EventSource;
    /**
     * Close the EventSource if it exists
     */
    closeEventSource(): void;
}
export declare const createHandyApi: (baseV3Url: string, baseV2Url: string, applicationId: string, connectionKey?: string) => HandyApi;