macromate-hid 1.0.0-beta.1

package/types/index.d.ts

@@ -0,0 +1,338 @@
+/**
+ * TypeScript declarations for macromate-hid
+ */
+
+export interface ControllerOptions {
+    /** Vendor ID (default: 0xCAFE) */
+    vid?: number;
+    /** Product ID (default: 0x4010) */
+    pid?: number;
+    /** Default command timeout in ms (default: 2000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+
+export interface CommandResult {
+    /** Status code (0 = OK) */
+    status: number;
+    /** Response data buffer */
+    data: Buffer;
+}
+
+export interface PingResult {
+    /** Firmware version string */
+    version: string;
+}
+
+export interface DeviceInfo {
+    vendorId: number;
+    productId: number;
+    path: string;
+    product?: string;
+    manufacturer?: string;
+    usagePage?: number;
+    usage?: number;
+    interface: number;
+}
+
+/**
+ * Main class for communicating with MacroMate device
+ */
+export class MacroController {
+    /** Vendor ID */
+    readonly vid: number;
+    /** Product ID */
+    readonly pid: number;
+    /** Default timeout (ms) */
+    readonly timeout: number;
+    /** Debug mode enabled */
+    readonly debug: boolean;
+    /** Check if device is connected */
+    readonly isConnected: boolean;
+    /** Device info (after connection) */
+    readonly deviceInfo: DeviceInfo | null;
+
+    constructor(options?: ControllerOptions);
+
+    /**
+     * Find all matching devices
+     */
+    static findDevices(vid?: number, pid?: number): DeviceInfo[];
+
+    /**
+     * List all HID devices with the specified VID
+     */
+    static listDevices(vid?: number): DeviceInfo[];
+
+    /**
+     * Connect to the device
+     * @throws Error if device not found or connection failed
+     */
+    connect(): boolean;
+
+    /**
+     * Disconnect from the device
+     */
+    disconnect(): void;
+
+    /**
+     * Send a raw command to the device
+     */
+    sendCommand(cmd: number, args?: number[], options?: { timeout?: number }): Promise<CommandResult>;
+
+    /**
+     * Send command without waiting for response (for bootloader)
+     */
+    sendCommandNoWait(cmd: number, args?: number[]): void;
+
+    // High-level API
+
+    /**
+     * Ping the device
+     * @returns Firmware version info
+     */
+    ping(): Promise<PingResult>;
+
+    /**
+     * Get firmware version
+     * @returns Version string (e.g., "1.0.0")
+     */
+    getVersion(): Promise<string>;
+
+    /**
+     * Enter bootloader mode (device will reboot)
+     * Connection will be lost after this command
+     */
+    enterBootloader(): void;
+
+    // Keyboard API
+
+    /**
+     * Press a key (and hold)
+     */
+    keyPress(keycode: number): Promise<void>;
+
+    /**
+     * Release a key
+     */
+    keyRelease(keycode: number): Promise<void>;
+
+    /**
+     * Tap a key (press and release)
+     */
+    keyTap(keycode: number): Promise<void>;
+
+    /**
+     * Set modifier keys (Ctrl, Shift, Alt, Win)
+     * @param modifiers Modifier flags (use MOD constants, can be combined with |)
+     */
+    setModifiers(modifiers: number): Promise<void>;
+
+    /**
+     * Release all keys and modifiers
+     */
+    releaseAll(): Promise<void>;
+
+    /**
+     * Type a string (ASCII only)
+     * @param text Text to type (max 62 characters per call)
+     */
+    typeString(text: string): Promise<void>;
+
+    /**
+     * Execute a keyboard shortcut (e.g., Ctrl+C)
+     */
+    shortcut(modifiers: number, keycode: number): Promise<void>;
+
+    // Mouse API
+
+    /**
+     * Move mouse relative to current position
+     * @param x X movement (-127 to 127)
+     * @param y Y movement (-127 to 127)
+     */
+    mouseMove(x: number, y: number): Promise<void>;
+
+    /**
+     * Click a mouse button
+     */
+    mouseClick(button?: number): Promise<void>;
+
+    /**
+     * Press a mouse button (and hold)
+     */
+    mousePress(button?: number): Promise<void>;
+
+    /**
+     * Release a mouse button
+     */
+    mouseRelease(button?: number): Promise<void>;
+
+    /**
+     * Scroll the mouse wheel
+     * @param amount Scroll amount (positive = up, negative = down)
+     */
+    mouseScroll(amount: number): Promise<void>;
+
+    /**
+     * Double-click a mouse button
+     */
+    mouseDoubleClick(button?: number, delay?: number): Promise<void>;
+
+    // Utility
+
+    /**
+     * Execute device-side delay
+     */
+    delay(ms: number): Promise<void>;
+}
+
+// HID Keycodes
+export const KEY: {
+    readonly A: number;
+    readonly B: number;
+    readonly C: number;
+    readonly D: number;
+    readonly E: number;
+    readonly F: number;
+    readonly G: number;
+    readonly H: number;
+    readonly I: number;
+    readonly J: number;
+    readonly K: number;
+    readonly L: number;
+    readonly M: number;
+    readonly N: number;
+    readonly O: number;
+    readonly P: number;
+    readonly Q: number;
+    readonly R: number;
+    readonly S: number;
+    readonly T: number;
+    readonly U: number;
+    readonly V: number;
+    readonly W: number;
+    readonly X: number;
+    readonly Y: number;
+    readonly Z: number;
+    readonly N1: number;
+    readonly N2: number;
+    readonly N3: number;
+    readonly N4: number;
+    readonly N5: number;
+    readonly N6: number;
+    readonly N7: number;
+    readonly N8: number;
+    readonly N9: number;
+    readonly N0: number;
+    readonly ENTER: number;
+    readonly ESC: number;
+    readonly BACKSPACE: number;
+    readonly TAB: number;
+    readonly SPACE: number;
+    readonly MINUS: number;
+    readonly EQUAL: number;
+    readonly BRACKET_LEFT: number;
+    readonly BRACKET_RIGHT: number;
+    readonly BACKSLASH: number;
+    readonly SEMICOLON: number;
+    readonly QUOTE: number;
+    readonly GRAVE: number;
+    readonly COMMA: number;
+    readonly PERIOD: number;
+    readonly SLASH: number;
+    readonly CAPS_LOCK: number;
+    readonly F1: number;
+    readonly F2: number;
+    readonly F3: number;
+    readonly F4: number;
+    readonly F5: number;
+    readonly F6: number;
+    readonly F7: number;
+    readonly F8: number;
+    readonly F9: number;
+    readonly F10: number;
+    readonly F11: number;
+    readonly F12: number;
+    readonly PRINT_SCREEN: number;
+    readonly SCROLL_LOCK: number;
+    readonly PAUSE: number;
+    readonly INSERT: number;
+    readonly HOME: number;
+    readonly PAGE_UP: number;
+    readonly DELETE: number;
+    readonly END: number;
+    readonly PAGE_DOWN: number;
+    readonly RIGHT: number;
+    readonly LEFT: number;
+    readonly DOWN: number;
+    readonly UP: number;
+    readonly NUM_LOCK: number;
+    readonly NUMPAD_SLASH: number;
+    readonly NUMPAD_ASTERISK: number;
+    readonly NUMPAD_MINUS: number;
+    readonly NUMPAD_PLUS: number;
+    readonly NUMPAD_ENTER: number;
+    readonly NUMPAD_1: number;
+    readonly NUMPAD_2: number;
+    readonly NUMPAD_3: number;
+    readonly NUMPAD_4: number;
+    readonly NUMPAD_5: number;
+    readonly NUMPAD_6: number;
+    readonly NUMPAD_7: number;
+    readonly NUMPAD_8: number;
+    readonly NUMPAD_9: number;
+    readonly NUMPAD_0: number;
+    readonly NUMPAD_PERIOD: number;
+};
+
+// Keyboard modifiers
+export const MOD: {
+    readonly CTRL: number;
+    readonly SHIFT: number;
+    readonly ALT: number;
+    readonly WIN: number;
+};
+
+// Mouse buttons
+export const MOUSE_BTN: {
+    readonly LEFT: number;
+    readonly RIGHT: number;
+    readonly MIDDLE: number;
+};
+
+// Command codes
+export const CMD: {
+    readonly PING: number;
+    readonly GET_VERSION: number;
+    readonly BOOTLOADER: number;
+    readonly KEY_PRESS: number;
+    readonly KEY_RELEASE: number;
+    readonly KEY_TAP: number;
+    readonly KEY_MODIFIER: number;
+    readonly KEY_RELEASE_ALL: number;
+    readonly KEY_TYPE_STRING: number;
+    readonly MOUSE_MOVE: number;
+    readonly MOUSE_CLICK: number;
+    readonly MOUSE_PRESS: number;
+    readonly MOUSE_RELEASE: number;
+    readonly MOUSE_SCROLL: number;
+    readonly DELAY: number;
+};
+
+// Status codes
+export const STATUS: {
+    readonly OK: number;
+    readonly ERROR_UNKNOWN: number;
+    readonly ERROR_INVALID: number;
+    readonly ERROR_OVERFLOW: number;
+};
+
+// Device config
+export const VID: number;
+export const PID: number;
+export const VENDOR_USAGE_PAGE: number;
+export const DEFAULT_TIMEOUT: number;
+export const TYPE_STRING_TIMEOUT: number;
+