@zendrex/buttplug.js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1752 @@
+import { z } from 'zod';
+import Emittery from 'emittery';
+
+/** Supported output actuator types in the Buttplug v4 protocol. */
+declare const OUTPUT_TYPE_VALUES: readonly ["Vibrate", "Rotate", "RotateWithDirection", "Oscillate", "Constrict", "Spray", "Temperature", "Led", "Position", "HwPositionWithDuration"];
+declare const OutputTypeSchema: z.ZodEnum<{
+    Vibrate: "Vibrate";
+    Rotate: "Rotate";
+    RotateWithDirection: "RotateWithDirection";
+    Oscillate: "Oscillate";
+    Constrict: "Constrict";
+    Spray: "Spray";
+    Temperature: "Temperature";
+    Led: "Led";
+    Position: "Position";
+    HwPositionWithDuration: "HwPositionWithDuration";
+}>;
+type OutputType = z.infer<typeof OutputTypeSchema>;
+/** Supported input sensor types in the Buttplug v4 protocol. */
+declare const INPUT_TYPE_VALUES: readonly ["Battery", "RSSI", "Pressure", "Button", "Position"];
+declare const InputTypeSchema: z.ZodEnum<{
+    Position: "Position";
+    Battery: "Battery";
+    RSSI: "RSSI";
+    Pressure: "Pressure";
+    Button: "Button";
+}>;
+type InputType = z.infer<typeof InputTypeSchema>;
+declare const InputCommandTypeSchema: z.ZodEnum<{
+    Read: "Read";
+    Subscribe: "Subscribe";
+    Unsubscribe: "Unsubscribe";
+}>;
+/** Input command operation: one-shot read, subscribe for updates, or unsubscribe. */
+type InputCommandType = z.infer<typeof InputCommandTypeSchema>;
+/**
+ * Unsigned scalar output command data wrapped in a `{Value}` object.
+ *
+ * Intiface Central expects `{"Vibrate": {"Value": 15}}`, not bare integers.
+ */
+declare const UnsignedScalarOutputDataSchema: z.ZodObject<{
+    Value: z.ZodNumber;
+}, z.core.$strip>;
+type UnsignedScalarOutputData = z.infer<typeof UnsignedScalarOutputDataSchema>;
+/**
+ * Signed scalar output command data wrapped in a `{Value}` object.
+ *
+ * Used by Temperature (positive = heat, negative = cool).
+ */
+declare const SignedScalarOutputDataSchema: z.ZodObject<{
+    Value: z.ZodNumber;
+}, z.core.$strip>;
+type SignedScalarOutputData = z.infer<typeof SignedScalarOutputDataSchema>;
+/** Alias for {@link UnsignedScalarOutputData}, used by most output types. */
+type ScalarOutputData = UnsignedScalarOutputData;
+/** Rotation output with explicit direction control. */
+declare const RotateWithDirectionOutputDataSchema: z.ZodObject<{
+    Value: z.ZodNumber;
+    Clockwise: z.ZodBoolean;
+}, z.core.$strip>;
+type RotateWithDirectionOutputData = z.infer<typeof RotateWithDirectionOutputDataSchema>;
+/**
+ * Hardware position output with duration for timed movements.
+ *
+ * Spec section: HwPositionWithDuration uses `Position` (not `Value`) and `Duration`.
+ */
+declare const HwPositionOutputDataSchema: z.ZodObject<{
+    Position: z.ZodNumber;
+    Duration: z.ZodNumber;
+}, z.core.$strip>;
+type HwPositionOutputData = z.infer<typeof HwPositionOutputDataSchema>;
+/**
+ * Tagged output command union discriminated by actuator type key.
+ *
+ * Each variant is a single-key object mapping the output type name to its data shape.
+ */
+declare const OutputCommandSchema: z.ZodUnion<readonly [z.ZodObject<{
+    Vibrate: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Rotate: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    RotateWithDirection: z.ZodObject<{
+        Value: z.ZodNumber;
+        Clockwise: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Oscillate: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Constrict: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Spray: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Temperature: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Led: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Position: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    HwPositionWithDuration: z.ZodObject<{
+        Position: z.ZodNumber;
+        Duration: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>]>;
+type OutputCommand = z.infer<typeof OutputCommandSchema>;
+/**
+ * Tagged union of all client messages.
+ *
+ * Each variant is a single-key object wrapping the specific message schema.
+ */
+declare const ClientMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    RequestServerInfo: z.ZodObject<{
+        Id: z.ZodNumber;
+        ClientName: z.ZodString;
+        ProtocolVersionMajor: z.ZodNumber;
+        ProtocolVersionMinor: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    StartScanning: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    StopScanning: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    RequestDeviceList: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Ping: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Disconnect: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    StopCmd: z.ZodObject<{
+        Id: z.ZodNumber;
+        DeviceIndex: z.ZodOptional<z.ZodNumber>;
+        FeatureIndex: z.ZodOptional<z.ZodNumber>;
+        Inputs: z.ZodOptional<z.ZodBoolean>;
+        Outputs: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    OutputCmd: z.ZodObject<{
+        Id: z.ZodNumber;
+        DeviceIndex: z.ZodNumber;
+        FeatureIndex: z.ZodNumber;
+        Command: z.ZodUnion<readonly [z.ZodObject<{
+            Vibrate: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Rotate: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            RotateWithDirection: z.ZodObject<{
+                Value: z.ZodNumber;
+                Clockwise: z.ZodBoolean;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Oscillate: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Constrict: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Spray: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Temperature: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Led: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Position: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            HwPositionWithDuration: z.ZodObject<{
+                Position: z.ZodNumber;
+                Duration: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>]>;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    InputCmd: z.ZodObject<{
+        Id: z.ZodNumber;
+        DeviceIndex: z.ZodNumber;
+        FeatureIndex: z.ZodNumber;
+        Type: z.ZodEnum<{
+            Position: "Position";
+            Battery: "Battery";
+            RSSI: "RSSI";
+            Pressure: "Pressure";
+            Button: "Button";
+        }>;
+        Command: z.ZodEnum<{
+            Read: "Read";
+            Subscribe: "Subscribe";
+            Unsubscribe: "Unsubscribe";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strict>]>;
+type ClientMessage = z.infer<typeof ClientMessageSchema>;
+/** Handshake response from the server with capabilities and timing requirements. */
+declare const ServerInfoSchema: z.ZodObject<{
+    Id: z.ZodNumber;
+    ServerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ProtocolVersionMajor: z.ZodNumber;
+    ProtocolVersionMinor: z.ZodNumber;
+    MaxPingTime: z.ZodNumber;
+}, z.core.$strip>;
+type ServerInfo = z.infer<typeof ServerInfoSchema>;
+/**
+ * Sensor reading value from a device.
+ *
+ * Intiface Central wraps sensor values in a `{Value}` object,
+ * e.g. `{"Battery": {"Value": 90}}`.
+ */
+declare const SensorValueSchema: z.ZodObject<{
+    Value: z.ZodNumber;
+}, z.core.$strip>;
+type SensorValue = z.infer<typeof SensorValueSchema>;
+/**
+ * Tagged sensor data union discriminated by sensor type key.
+ *
+ * Each variant maps a sensor type name to its {@link SensorValue}.
+ */
+declare const InputDataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    Battery: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    RSSI: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Pressure: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Button: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Position: z.ZodObject<{
+        Value: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>]>;
+type InputData = z.infer<typeof InputDataSchema>;
+/** Server message delivering a sensor reading from a device. */
+declare const InputReadingSchema: z.ZodObject<{
+    Id: z.ZodNumber;
+    DeviceIndex: z.ZodNumber;
+    FeatureIndex: z.ZodNumber;
+    Reading: z.ZodUnion<readonly [z.ZodObject<{
+        Battery: z.ZodObject<{
+            Value: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>, z.ZodObject<{
+        RSSI: z.ZodObject<{
+            Value: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>, z.ZodObject<{
+        Pressure: z.ZodObject<{
+            Value: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>, z.ZodObject<{
+        Button: z.ZodObject<{
+            Value: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>, z.ZodObject<{
+        Position: z.ZodObject<{
+            Value: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>]>;
+}, z.core.$strip>;
+type InputReading = z.infer<typeof InputReadingSchema>;
+/** Raw device descriptor as reported by the server, before normalization. */
+declare const RawDeviceSchema: z.ZodObject<{
+    DeviceName: z.ZodString;
+    DeviceIndex: z.ZodNumber;
+    DeviceMessageTimingGap: z.ZodNumber;
+    DeviceDisplayName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    DeviceFeatures: z.ZodRecord<z.ZodString, z.ZodObject<{
+        FeatureIndex: z.ZodNumber;
+        FeatureDescription: z.ZodString;
+        Output: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+            Value: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+            Duration: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strip>>>>;
+        Input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+            Command: z.ZodArray<z.ZodEnum<{
+                Read: "Read";
+                Subscribe: "Subscribe";
+                Unsubscribe: "Unsubscribe";
+            }>>;
+            Value: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type RawDevice = z.infer<typeof RawDeviceSchema>;
+/**
+ * Tagged union of all server messages.
+ *
+ * Each variant is a single-key object wrapping the specific message schema.
+ */
+declare const ServerMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ServerInfo: z.ZodObject<{
+        Id: z.ZodNumber;
+        ServerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ProtocolVersionMajor: z.ZodNumber;
+        ProtocolVersionMinor: z.ZodNumber;
+        MaxPingTime: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Ok: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    Error: z.ZodObject<{
+        Id: z.ZodNumber;
+        ErrorCode: z.ZodEnum<{
+            readonly UNKNOWN: 0;
+            readonly INIT: 1;
+            readonly PING: 2;
+            readonly MESSAGE: 3;
+            readonly DEVICE: 4;
+        }>;
+        ErrorMessage: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    DeviceList: z.ZodObject<{
+        Id: z.ZodNumber;
+        Devices: z.ZodRecord<z.ZodString, z.ZodObject<{
+            DeviceName: z.ZodString;
+            DeviceIndex: z.ZodNumber;
+            DeviceMessageTimingGap: z.ZodNumber;
+            DeviceDisplayName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            DeviceFeatures: z.ZodRecord<z.ZodString, z.ZodObject<{
+                FeatureIndex: z.ZodNumber;
+                FeatureDescription: z.ZodString;
+                Output: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    Value: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+                    Duration: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, z.core.$strip>>>>;
+                Input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    Command: z.ZodArray<z.ZodEnum<{
+                        Read: "Read";
+                        Subscribe: "Subscribe";
+                        Unsubscribe: "Unsubscribe";
+                    }>>;
+                    Value: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, z.core.$strip>>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    ScanningFinished: z.ZodObject<{
+        Id: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    InputReading: z.ZodObject<{
+        Id: z.ZodNumber;
+        DeviceIndex: z.ZodNumber;
+        FeatureIndex: z.ZodNumber;
+        Reading: z.ZodUnion<readonly [z.ZodObject<{
+            Battery: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            RSSI: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Pressure: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Button: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>, z.ZodObject<{
+            Position: z.ZodObject<{
+                Value: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>]>;
+    }, z.core.$strip>;
+}, z.core.$strict>]>;
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+/** Normalized output feature descriptor with type, index, and capabilities. */
+declare const OutputFeatureSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        Vibrate: "Vibrate";
+        Rotate: "Rotate";
+        RotateWithDirection: "RotateWithDirection";
+        Oscillate: "Oscillate";
+        Constrict: "Constrict";
+        Spray: "Spray";
+        Temperature: "Temperature";
+        Led: "Led";
+        Position: "Position";
+        HwPositionWithDuration: "HwPositionWithDuration";
+    }>;
+    index: z.ZodNumber;
+    description: z.ZodString;
+    range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    durationRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+type OutputFeature = z.infer<typeof OutputFeatureSchema>;
+/**
+ * Normalized input feature descriptor with type, index, and command capabilities.
+ *
+ * Spec section: Input Capability Object — Value is a single `[min, max]` range.
+ */
+declare const InputFeatureSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        Position: "Position";
+        Battery: "Battery";
+        RSSI: "RSSI";
+        Pressure: "Pressure";
+        Button: "Button";
+    }>;
+    index: z.ZodNumber;
+    description: z.ZodString;
+    range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    canRead: z.ZodBoolean;
+    canSubscribe: z.ZodBoolean;
+}, z.core.$strip>;
+type InputFeature = z.infer<typeof InputFeatureSchema>;
+/** Collection of normalized input and output features for a device. */
+declare const DeviceFeaturesSchema: z.ZodObject<{
+    outputs: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            Vibrate: "Vibrate";
+            Rotate: "Rotate";
+            RotateWithDirection: "RotateWithDirection";
+            Oscillate: "Oscillate";
+            Constrict: "Constrict";
+            Spray: "Spray";
+            Temperature: "Temperature";
+            Led: "Led";
+            Position: "Position";
+            HwPositionWithDuration: "HwPositionWithDuration";
+        }>;
+        index: z.ZodNumber;
+        description: z.ZodString;
+        range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        durationRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    inputs: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            Position: "Position";
+            Battery: "Battery";
+            RSSI: "RSSI";
+            Pressure: "Pressure";
+            Button: "Button";
+        }>;
+        index: z.ZodNumber;
+        description: z.ZodString;
+        range: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        canRead: z.ZodBoolean;
+        canSubscribe: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type DeviceFeatures = z.infer<typeof DeviceFeaturesSchema>;
+declare const FeatureValueSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    value: z.ZodNumber;
+}, z.core.$strip>;
+/** Feature index paired with a scalar value, used for batch output commands. */
+type FeatureValue = z.infer<typeof FeatureValueSchema>;
+/** Feature index paired with speed and direction for rotation commands. */
+declare const RotationValueSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    speed: z.ZodNumber;
+    clockwise: z.ZodBoolean;
+}, z.core.$strip>;
+type RotationValue = z.infer<typeof RotationValueSchema>;
+/** Feature index paired with position and duration for timed movement commands. */
+declare const PositionValueSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    position: z.ZodNumber;
+    duration: z.ZodNumber;
+}, z.core.$strip>;
+type PositionValue = z.infer<typeof PositionValueSchema>;
+
+/** Callback invoked when a sensor subscription delivers a new reading. */
+type SensorCallback = (value: number) => void;
+/**
+ * Interface for sending protocol messages and managing sensor subscriptions.
+ *
+ * Implemented by the client to provide the transport layer that
+ * {@link Device} instances use for communication with the server.
+ */
+interface DeviceMessageSender {
+    /**
+     * Allocates the next unique message ID for request/response correlation.
+     *
+     * @returns A monotonically increasing integer within the valid ID range
+     */
+    nextId(): number;
+    /**
+     * Registers a callback to receive sensor readings for a specific subscription.
+     *
+     * @param key - Unique subscription key from {@link sensorKey}
+     * @param callback - Function invoked with each sensor value
+     * @param info - Metadata identifying the device, feature, and sensor type
+     */
+    registerSensorSubscription(key: string, callback: SensorCallback, info: {
+        deviceIndex: number;
+        featureIndex: number;
+        type: InputType;
+    }): void;
+    /**
+     * Sends one or more client messages and waits for the server's responses.
+     *
+     * @param messages - A single message or array of messages to send
+     * @returns The server's response messages
+     */
+    send(messages: ClientMessage | ClientMessage[]): Promise<ServerMessage[]>;
+    /**
+     * Removes a previously registered sensor subscription.
+     *
+     * @param key - The subscription key to unregister
+     */
+    unregisterSensorSubscription(key: string): void;
+}
+
+/**
+ * Represents a single device connected to a Buttplug server.
+ *
+ * Provides typed methods for controlling outputs (vibration, rotation, position, etc.)
+ * and reading or subscribing to input sensors. Constructed internally by {@link ButtplugClient}
+ * when devices are discovered.
+ */
+declare class Device {
+    #private;
+    constructor(options: DeviceOptions);
+    /**
+     * Sets vibration intensity on all or individual motors.
+     *
+     * @param intensity - A single value for all motors, or per-motor {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support vibration
+     */
+    vibrate(intensity: number | FeatureValue[]): Promise<void>;
+    /**
+     * Sets oscillation speed on all or individual motors.
+     *
+     * @param speed - A single value for all motors, or per-motor {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support oscillation
+     */
+    oscillate(speed: number | FeatureValue[]): Promise<void>;
+    /**
+     * Sets constriction pressure on all or individual actuators.
+     *
+     * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support constriction
+     */
+    constrict(value: number | FeatureValue[]): Promise<void>;
+    /**
+     * Controls spray output on all or individual actuators.
+     *
+     * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support spraying
+     */
+    spray(value: number | FeatureValue[]): Promise<void>;
+    /**
+     * Sets temperature on all or individual actuators.
+     *
+     * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support temperature control
+     */
+    temperature(value: number | FeatureValue[]): Promise<void>;
+    /**
+     * Controls LED brightness on all or individual actuators.
+     *
+     * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+     * @throws DeviceError if the device does not support LED control
+     */
+    led(value: number | FeatureValue[]): Promise<void>;
+    /**
+     * Sets rotation speed on per-motor {@link RotationValue} entries with individual direction.
+     *
+     * @param values - Per-motor rotation entries with speed and direction
+     * @throws DeviceError if the device does not support rotation
+     */
+    rotate(values: RotationValue[]): Promise<void>;
+    /**
+     * Sets rotation speed (and optionally direction) on all motors.
+     *
+     * Automatically selects `RotateWithDirection` if the device supports it,
+     * falling back to `Rotate` otherwise.
+     *
+     * @param speed - A single speed for all motors
+     * @param options - Direction options (defaults to clockwise)
+     * @throws DeviceError if the device does not support rotation
+     */
+    rotate(speed: number, options?: {
+        clockwise?: boolean;
+    }): Promise<void>;
+    /**
+     * Moves per-axis {@link PositionValue} entries with individual durations.
+     *
+     * @param values - Per-axis position entries with position and duration
+     * @throws DeviceError if the device does not support position control
+     */
+    position(values: PositionValue[]): Promise<void>;
+    /**
+     * Moves all axes to a uniform position over a given duration.
+     *
+     * Automatically selects `HwPositionWithDuration` if the device supports it,
+     * falling back to `Position` otherwise.
+     *
+     * @param position - A single position value for all axes
+     * @param options - Movement options including duration in milliseconds
+     * @throws DeviceError if the device does not support position control
+     */
+    position(position: number, options: {
+        duration: number;
+    }): Promise<void>;
+    /**
+     * Stops activity on this device.
+     *
+     * Can target a specific feature index or filter by input/output type.
+     * Without options, stops all features.
+     *
+     * @param options - Optional filters for which features to stop
+     * @throws DeviceError if the specified feature index does not exist
+     */
+    stop(options?: DeviceStopOptions): Promise<void>;
+    /**
+     * Sends a raw output command to a specific feature.
+     *
+     * Values are validated against the feature's declared range and clamped if out of bounds.
+     *
+     * @param options - The feature index and output command payload
+     * @throws DeviceError if no matching output feature exists at the given index
+     */
+    output(options: DeviceOutputOptions): Promise<void>;
+    /**
+     * Performs a one-shot read of a sensor value.
+     *
+     * @param type - The sensor type to read (e.g. `"Battery"`, `"RSSI"`)
+     * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+     * @returns The numeric sensor value
+     * @throws DeviceError if the sensor does not exist or does not support reading
+     */
+    readSensor(type: InputType, sensorIndex?: number): Promise<number>;
+    /**
+     * Subscribes to continuous sensor readings.
+     *
+     * @param type - The sensor type to subscribe to
+     * @param callback - Invoked each time a new reading arrives
+     * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+     * @returns An async unsubscribe function that stops the subscription
+     * @throws DeviceError if the sensor does not exist or does not support subscriptions
+     */
+    subscribeSensor(type: InputType, callback: SensorCallback, sensorIndex?: number): Promise<() => Promise<void>>;
+    /**
+     * Explicitly unsubscribes from a sensor subscription by type and sensor index.
+     *
+     * @param type - The sensor type to unsubscribe from
+     * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+     */
+    unsubscribe(type: InputType, sensorIndex?: number): Promise<void>;
+    /**
+     * Checks whether this device supports a given output type.
+     *
+     * @param type - The output type to check
+     * @returns `true` if at least one feature supports the output type
+     */
+    canOutput(type: OutputType): boolean;
+    /**
+     * Checks whether this device can perform a one-shot read of a given sensor type.
+     *
+     * @param type - The input type to check
+     * @returns `true` if at least one matching sensor supports reading
+     */
+    canRead(type: InputType): boolean;
+    /**
+     * Checks whether this device supports subscriptions for a given sensor type.
+     *
+     * @param type - The input type to check
+     * @returns `true` if at least one matching sensor supports subscriptions
+     */
+    canSubscribe(type: InputType): boolean;
+    /** Server-assigned device index. */
+    get index(): number;
+    /** Internal device name from firmware. */
+    get name(): string;
+    /** User-facing display name, or `null` if the server did not provide one. */
+    get displayName(): string | null;
+    /** Minimum interval in milliseconds between messages recommended by the server. */
+    get messageTimingGap(): number;
+    /** Parsed input and output feature descriptors for this device. */
+    get features(): DeviceFeatures;
+    /** Whether this device supports any form of rotation output. */
+    get canRotate(): boolean;
+    /** Whether this device supports any form of position output. */
+    get canPosition(): boolean;
+}
+
+/**
+ * Structured logging interface for Buttplug components.
+ *
+ * Supports hierarchical prefixes via {@link Logger.child} for scoped logging.
+ */
+interface Logger {
+    /**
+     * Creates a child logger with a nested prefix.
+     *
+     * @param prefix - Label appended to the parent prefix, separated by ':'
+     * @returns A new {@link Logger} with the combined prefix
+     */
+    child(prefix: string): Logger;
+    /** Logs a debug-level message. */
+    debug(message: string): void;
+    /** Logs an error-level message. */
+    error(message: string): void;
+    /** Logs an info-level message. */
+    info(message: string): void;
+    /** Logs a warning-level message. */
+    warn(message: string): void;
+}
+/**
+ * A logger that silently discards all messages.
+ * Used as the default when no logging is configured.
+ */
+declare const noopLogger: Logger;
+/** Default console logger prefixed with "buttplug". */
+declare const consoleLogger: Logger;
+
+/**
+ * Construction options for a {@link Device} instance.
+ */
+interface DeviceOptions {
+    /** The {@link DeviceMessageSender} used to route messages to the server. */
+    client: DeviceMessageSender;
+    /** Optional logger for device-level diagnostics. */
+    logger?: Logger;
+    /** Raw device descriptor received from the server during enumeration. */
+    raw: RawDevice;
+}
+/**
+ * Event map for the {@link ButtplugClient} emitter.
+ *
+ * Each key is an event name and its value is the payload type passed to listeners.
+ */
+interface ClientEventMap {
+    /** Emitted after a successful connection and handshake. */
+    connected: undefined;
+    /** Emitted when a new device is discovered. */
+    deviceAdded: {
+        device: Device;
+    };
+    /** Emitted with the full device list after a reconciliation pass. */
+    deviceList: {
+        devices: Device[];
+    };
+    /** Emitted when a previously known device is removed. */
+    deviceRemoved: {
+        device: Device;
+    };
+    /** Emitted when a device's metadata is updated by the server. */
+    deviceUpdated: {
+        device: Device;
+        previousDevice: Device;
+    };
+    /** Emitted when the WebSocket connection closes. */
+    disconnected: {
+        reason?: string;
+    };
+    /** Emitted when a transport or protocol error occurs. */
+    error: {
+        error: Error;
+    };
+    /** Emitted when the server pushes an input sensor reading. */
+    inputReading: {
+        reading: InputReading;
+    };
+    /** Emitted after a successful reconnection and re-handshake. */
+    reconnected: undefined;
+    /** Emitted on each reconnection attempt with the current attempt number. */
+    reconnecting: {
+        attempt: number;
+    };
+    /** Emitted when the server finishes a device scan. */
+    scanningFinished: undefined;
+}
+/**
+ * Options for {@link Device.stop}.
+ *
+ * Without any options, stops all features on the device.
+ * Provide filters to target specific features or feature types.
+ */
+interface DeviceStopOptions {
+    /** Stop a specific feature by index. */
+    featureIndex?: number;
+    /** Stop only input features (unsubscribes sensors). */
+    inputs?: boolean;
+    /** Stop only output features. */
+    outputs?: boolean;
+}
+/**
+ * Options for {@link Device.output}.
+ *
+ * Sends a raw {@link OutputCommand} to a specific feature on the device.
+ */
+interface DeviceOutputOptions {
+    /** The output command payload. */
+    command: OutputCommand;
+    /** Target feature index on this device. */
+    featureIndex: number;
+}
+/**
+ * Configuration options for {@link ButtplugClient}.
+ */
+interface ButtplugClientOptions {
+    /** Whether to automatically send pings to keep the connection alive. Defaults to `true`. */
+    autoPing?: boolean;
+    /** Whether to automatically reconnect on connection loss. */
+    autoReconnect?: boolean;
+    /** Display name sent to the server during handshake. */
+    clientName?: string;
+    /** Logger instance for client diagnostics. */
+    logger?: Logger;
+    /** Maximum number of reconnection attempts before giving up. */
+    maxReconnectAttempts?: number;
+    /** Maximum delay in milliseconds between reconnection attempts (exponential backoff cap). */
+    maxReconnectDelay?: number;
+    /** Initial delay in milliseconds before the first reconnection attempt. */
+    reconnectDelay?: number;
+    /** Timeout in milliseconds for individual protocol requests. */
+    requestTimeout?: number;
+}
+
+/**
+ * High-level client for communicating with a Buttplug server over WebSocket.
+ *
+ * Manages the full connection lifecycle including handshake, device discovery,
+ * ping keep-alive, sensor subscriptions, and optional automatic reconnection.
+ * Emits events defined in {@link ClientEventMap}.
+ */
+declare class ButtplugClient extends Emittery<ClientEventMap> implements DeviceMessageSender {
+    #private;
+    constructor(url: string, options?: ButtplugClientOptions);
+    /**
+     * Opens a WebSocket connection and performs the Buttplug handshake.
+     *
+     * @throws ConnectionError if the transport fails to connect
+     * @throws HandshakeError if the server rejects the handshake
+     */
+    connect(): Promise<void>;
+    /**
+     * Gracefully disconnects from the server.
+     *
+     * Stops all devices, sends a protocol-level disconnect message, then closes
+     * the WebSocket. Both stop and disconnect steps are time-bounded so the
+     * method does not hang indefinitely.
+     *
+     * @param reason - Optional human-readable reason for the disconnection
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Begins scanning for devices on the server.
+     *
+     * @throws ConnectionError if the client is not connected
+     */
+    startScanning(): Promise<void>;
+    /**
+     * Stops an active device scan on the server.
+     *
+     * @throws ConnectionError if the client is not connected
+     */
+    stopScanning(): Promise<void>;
+    /**
+     * Sends a global stop command to halt all devices on the server.
+     *
+     * @throws ConnectionError if the client is not connected
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Requests the current device list from the server.
+     *
+     * The response triggers device reconciliation and emits
+     * `deviceAdded`, `deviceRemoved`, `deviceUpdated`, and `deviceList` events.
+     *
+     * @throws ConnectionError if the client is not connected
+     */
+    requestDeviceList(): Promise<void>;
+    /**
+     * Sends one or more raw protocol messages to the server.
+     *
+     * @param messages - A single message or array of messages to send
+     * @returns Server response messages
+     * @throws ConnectionError if the client is not connected
+     */
+    send(messages: ClientMessage | ClientMessage[]): Promise<ServerMessage[]>;
+    /**
+     * Returns the next monotonically increasing message ID.
+     *
+     * @returns A unique message ID for the next outgoing message
+     */
+    nextId(): number;
+    /**
+     * Registers a callback for incoming sensor readings.
+     *
+     * @param key - Unique subscription key (typically from `sensorKey()`)
+     * @param callback - Function invoked when a matching reading arrives
+     * @param info - Device, feature, and input type identifying the subscription
+     */
+    registerSensorSubscription(key: string, callback: SensorCallback, info: {
+        deviceIndex: number;
+        featureIndex: number;
+        type: InputType;
+    }): void;
+    /**
+     * Removes a previously registered sensor subscription.
+     *
+     * @param key - The subscription key to remove
+     */
+    unregisterSensorSubscription(key: string): void;
+    /**
+     * Retrieves a device by its server-assigned index.
+     *
+     * @param index - The device index
+     * @returns The {@link Device} instance, or `undefined` if not found
+     */
+    getDevice(index: number): Device | undefined;
+    /** Whether the WebSocket transport is currently connected. */
+    get connected(): boolean;
+    /** Whether a device scan is currently in progress. */
+    get scanning(): boolean;
+    /** Server information received during handshake, or `null` if not connected. */
+    get serverInfo(): ServerInfo | null;
+    /** Snapshot of all currently known {@link Device} instances. */
+    get devices(): Device[];
+}
+
+/** Constraint for event maps used with {@link TypedEmitter}. */
+type EventMap = Record<string, unknown>;
+/**
+ * A strongly-typed event emitter backed by Emittery.
+ *
+ * @typeParam T - An {@link EventMap} defining event names and their payload types
+ */
+type TypedEmitter<T extends EventMap> = Emittery<T>;
+
+/** Numeric error codes returned by the Buttplug protocol. */
+declare const ErrorCode: {
+    readonly UNKNOWN: 0;
+    readonly INIT: 1;
+    readonly PING: 2;
+    readonly MESSAGE: 3;
+    readonly DEVICE: 4;
+};
+/** Union type of all valid Buttplug error codes. */
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Base error class for all Buttplug-related failures. */
+declare class ButtplugError extends Error {
+    readonly name: string;
+    /**
+     * @param message - Human-readable error description
+     * @param cause - The underlying error that caused this failure
+     */
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when a WebSocket or transport connection fails.
+ */
+declare class ConnectionError extends ButtplugError {
+    readonly name: string;
+}
+/**
+ * Error thrown when the initial protocol handshake with the server fails.
+ */
+declare class HandshakeError extends ButtplugError {
+    readonly name: string;
+}
+/**
+ * Error thrown when the server returns a protocol-level error message.
+ */
+declare class ProtocolError extends ButtplugError {
+    readonly name: string;
+    /** The protocol {@link ErrorCode} returned by the server. */
+    readonly code: ErrorCode;
+    /**
+     * @param code - The protocol error code
+     * @param message - Human-readable error description
+     * @param cause - The underlying error that caused this failure
+     */
+    constructor(code: ErrorCode, message: string, cause?: Error);
+}
+/**
+ * Error thrown when a device-specific operation fails.
+ */
+declare class DeviceError extends ButtplugError {
+    readonly name: string;
+    /** Index of the device that triggered the error. */
+    readonly deviceIndex: number;
+    /**
+     * @param deviceIndex - Index of the device that triggered the error
+     * @param message - Human-readable error description
+     * @param cause - The underlying error that caused this failure
+     */
+    constructor(deviceIndex: number, message: string, cause?: Error);
+}
+/**
+ * Error thrown when an operation exceeds its allowed duration.
+ */
+declare class TimeoutError extends ButtplugError {
+    readonly name: string;
+    /** Name of the operation that timed out. */
+    readonly operation: string;
+    /** Duration in milliseconds before the timeout triggered. */
+    readonly timeoutMs: number;
+    /**
+     * @param operation - Name of the operation that timed out
+     * @param timeoutMs - Duration in milliseconds before the timeout triggered
+     * @param cause - The underlying error that caused this failure
+     */
+    constructor(operation: string, timeoutMs: number, cause?: Error);
+}
+/**
+ * Normalizes an unknown thrown value into a human-readable message.
+ *
+ * @param err - The caught value to format
+ * @returns Error message for Error instances, stringified value otherwise
+ */
+declare function formatError(err: unknown): string;
+
+/**
+ * Returns the {@link Logger} from the current context.
+ *
+ * Falls back to {@link noopLogger} when called outside a `runWithLogger` scope.
+ *
+ * @returns The context-scoped logger, or noop if none is set
+ */
+declare function getLogger(): Logger;
+/**
+ * Executes a function with the given {@link Logger} scoped to the
+ * current synchronous call stack.
+ *
+ * All downstream calls to {@link getLogger} within `fn` will receive
+ * the provided logger for the duration of the synchronous execution.
+ *
+ * @param logger - The logger to make available via `getLogger()`
+ * @param fn - The function to execute within the scoped context
+ * @returns The return value of `fn`
+ */
+declare function runWithLogger<T>(logger: Logger, fn: () => T): T;
+
+/** Major version of the Buttplug protocol this library implements (v4). */
+declare const PROTOCOL_VERSION_MAJOR = 4;
+/** Minor version of the Buttplug protocol this library implements. */
+declare const PROTOCOL_VERSION_MINOR = 0;
+/** Default client name sent during the handshake with a Buttplug server. */
+declare const DEFAULT_CLIENT_NAME = "buttplug.js";
+/** Default timeout in milliseconds for awaiting a server response to a request. */
+declare const DEFAULT_REQUEST_TIMEOUT = 10000;
+/** Default interval in milliseconds between keep-alive ping messages. */
+declare const DEFAULT_PING_INTERVAL = 1000;
+/** Maximum allowed message ID value (32-bit unsigned integer ceiling). */
+declare const MAX_MESSAGE_ID = 4294967295;
+
+/**
+ * Event handler signatures emitted by a {@link Transport}.
+ */
+interface TransportEvents {
+    /** Provides the WebSocket close code and reason for diagnostics. */
+    close: (code: number, reason: string) => void;
+    error: (error: Error) => void;
+    message: (data: string) => void;
+    open: () => void;
+}
+/**
+ * Lifecycle state of a {@link Transport} connection.
+ */
+type TransportState = "disconnected" | "connecting" | "connected";
+/**
+ * Union of event names that a {@link Transport} can emit.
+ */
+type TransportEventName = keyof TransportEvents;
+/**
+ * Base options shared across {@link Transport} implementations.
+ */
+interface TransportOptions {
+    logger?: Logger;
+}
+/**
+ * Minimal contract for a bidirectional message transport.
+ *
+ * Implementations handle the underlying connection lifecycle (connect, disconnect, send)
+ * and expose an event-based API for incoming data and state changes.
+ */
+interface Transport {
+    /**
+     * Opens a connection to the given URL.
+     *
+     * @param url - The WebSocket endpoint to connect to
+     */
+    connect(url: string): Promise<void>;
+    /**
+     * Closes the active connection.
+     *
+     * Implementations should handle cleanup and emit a "close" event.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Removes a previously registered handler for the given event.
+     *
+     * @param event - The event to stop listening for
+     * @param handler - The callback to remove
+     */
+    off<E extends TransportEventName>(event: E, handler: TransportEvents[E]): void;
+    /**
+     * Subscribes a handler for the given event.
+     *
+     * @param event - The event to listen for
+     * @param handler - The callback to invoke when the event fires
+     */
+    on<E extends TransportEventName>(event: E, handler: TransportEvents[E]): void;
+    /**
+     * Sends a text message over the active connection.
+     *
+     * @param data - The string payload to send
+     * @throws {ConnectionError} if the transport is not connected
+     */
+    send(data: string): void;
+    readonly state: TransportState;
+}
+
+/**
+ * Configuration for {@link PingManager}.
+ */
+interface PingOptions {
+    /** Whether to automatically send periodic pings. Defaults to `true`. */
+    autoPing?: boolean;
+    /** Cancels an in-flight ping with the given error (e.g. on timeout). */
+    cancelPing: (error: Error) => void;
+    /** Returns whether the transport is currently connected. */
+    isConnected: () => boolean;
+    /** Optional logger for ping diagnostics. Defaults to a no-op logger. */
+    logger?: Logger;
+    /** Called to initiate a disconnect when a ping times out while still connected. */
+    onDisconnect: (reason: string) => Promise<void>;
+    /** Called when a ping fails with a non-timeout error. */
+    onError: (error: Error) => void;
+    /** Sends a protocol-level ping and resolves when the pong arrives. */
+    sendPing: () => Promise<void>;
+}
+/**
+ * Schedules periodic keep-alive pings over a {@link Transport} and triggers
+ * disconnect when the server stops responding within the allowed time.
+ *
+ * **Important**: Callers must call {@link PingManager.stop} when the transport
+ * disconnects. The PingManager does not subscribe to transport events directly.
+ */
+declare class PingManager {
+    #private;
+    constructor(options: PingOptions);
+    /**
+     * Starts the periodic ping timer.
+     *
+     * The ping interval is 60% of `maxPingTime`, clamped to a minimum of 100ms.
+     * Stops any previously running timer before starting a new one.
+     *
+     * **Important**: Callers must call {@link PingManager.stop} when the transport
+     * disconnects to prevent pings from being sent to a closed connection.
+     *
+     * @param maxPingTime - Maximum time in ms the server allows between pings
+     */
+    start(maxPingTime: number): void;
+    /** Stops the ping timer and resets in-flight state. */
+    stop(): void;
+}
+
+/**
+ * Configuration for {@link ReconnectHandler}.
+ */
+interface ReconnectOptions {
+    /** Optional logger for reconnection diagnostics. Defaults to a no-op logger. */
+    logger?: Logger;
+    /** Maximum number of reconnect attempts before giving up. Defaults to 10. */
+    maxReconnectAttempts?: number;
+    /** Upper bound in ms for exponential backoff. Defaults to 30000ms. */
+    maxReconnectDelay?: number;
+    /** Called when all reconnect attempts are exhausted. */
+    onFailed?: (reason: string) => void;
+    /** Called when reconnection succeeds. */
+    onReconnected?: () => void;
+    /** Called before each reconnect attempt with the current attempt number. */
+    onReconnecting?: (attempt: number) => void;
+    /** Base delay in ms before the first reconnect attempt. Defaults to 1000ms. */
+    reconnectDelay?: number;
+    /** The {@link Transport} instance to reconnect. */
+    transport: Transport;
+    /** The WebSocket endpoint URL to reconnect to. */
+    url: string;
+}
+/**
+ * Manages automatic reconnection to a {@link Transport} using exponential backoff.
+ *
+ * Attempts are scheduled with increasing delays up to {@link ReconnectOptions.maxReconnectDelay},
+ * and stop after {@link ReconnectOptions.maxReconnectAttempts} failures.
+ */
+declare class ReconnectHandler {
+    #private;
+    constructor(options: ReconnectOptions);
+    /**
+     * Begins the reconnection sequence.
+     *
+     * No-ops if a reconnection is already in progress.
+     */
+    start(): void;
+    /** Cancels the reconnection sequence and clears any pending timers. */
+    cancel(): void;
+    /** Whether a reconnection sequence is currently in progress. */
+    get active(): boolean;
+}
+
+/**
+ * Configuration for {@link WebSocketTransport}.
+ */
+interface WebSocketTransportOptions {
+    /** Optional logger for connection diagnostics. Defaults to a no-op logger. */
+    logger?: Logger;
+}
+/**
+ * {@link Transport} implementation backed by a native WebSocket.
+ *
+ * Manages the full connection lifecycle including opening, closing,
+ * message dispatch, and event propagation.
+ */
+declare class WebSocketTransport implements Transport {
+    #private;
+    constructor(options?: WebSocketTransportOptions);
+    /**
+     * Opens a WebSocket connection to the given URL.
+     *
+     * Returns immediately if already connected. Deduplicates concurrent
+     * connect calls by returning the same in-flight promise.
+     *
+     * @param url - The WebSocket endpoint to connect to
+     * @throws {ConnectionError} if the connection fails or is closed during handshake
+     */
+    connect(url: string): Promise<void>;
+    /**
+     * Closes the active WebSocket connection.
+     *
+     * No-ops if already disconnected. Waits for the close handshake to complete
+     * if the socket is currently open or closing.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sends a text message over the active WebSocket.
+     *
+     * @param data - The string payload to send
+     * @throws {ConnectionError} if the WebSocket is not in the OPEN state or send fails
+     */
+    send(data: string): void;
+    /**
+     * Subscribes a handler for the given transport event.
+     *
+     * @param event - The event to listen for
+     * @param handler - The callback to invoke when the event fires
+     */
+    on<E extends TransportEventName>(event: E, handler: TransportEvents[E]): void;
+    /**
+     * Removes a previously registered handler for the given event.
+     *
+     * @param event - The event to stop listening for
+     * @param handler - The callback to remove
+     */
+    off<E extends TransportEventName>(event: E, handler: TransportEvents[E]): void;
+    /** Current connection lifecycle state. */
+    get state(): TransportState;
+}
+
+/**
+ * Default values for {@link ReconnectHandler} configuration.
+ *
+ * - `DELAY` — Base delay in ms before the first reconnect attempt
+ * - `MAX_DELAY` — Upper bound in ms for exponential backoff
+ * - `MAX_ATTEMPTS` — Maximum number of reconnect attempts before giving up
+ */
+declare const ReconnectDefaults: {
+    readonly DELAY: 1000;
+    readonly MAX_DELAY: 30000;
+    readonly MAX_ATTEMPTS: 10;
+};
+
+/** All {@link OutputType} values defined by the buttplug protocol. */
+declare const OUTPUT_TYPES: readonly OutputType[];
+/** All {@link InputType} values defined by the buttplug protocol. */
+declare const INPUT_TYPES: readonly InputType[];
+
+/**
+ * Minimal device interface required by {@link PatternEngine}.
+ *
+ * Decouples the pattern system from the full client device implementation,
+ * allowing patterns to target any object that can send {@link OutputCommand} messages.
+ */
+interface PatternDevice {
+    /** Available input/output features on the device. */
+    readonly features: DeviceFeatures;
+    /** Device index in the server's device list. */
+    readonly index: number;
+    /** Minimum interval in milliseconds between consecutive messages to this device. */
+    readonly messageTimingGap: number;
+    /** Human-readable device name. */
+    readonly name: string;
+    /**
+     * Sends an {@link OutputCommand} to a specific feature.
+     *
+     * @param options - The feature index and output command to send
+     */
+    output(options: DeviceOutputOptions): Promise<void>;
+    /**
+     * Stops device output.
+     *
+     * @param options - Optional filters for which features/directions to stop
+     */
+    stop(options?: DeviceStopOptions): Promise<void>;
+}
+/** Supported {@link Easing} curve names. */
+declare const EASING_VALUES: readonly ["linear", "easeIn", "easeOut", "easeInOut", "step"];
+/** Zod schema for validating {@link Easing} values. */
+declare const EasingSchema: z.ZodEnum<{
+    linear: "linear";
+    easeIn: "easeIn";
+    easeOut: "easeOut";
+    easeInOut: "easeInOut";
+    step: "step";
+}>;
+/** Easing curve identifier used for keyframe interpolation. */
+type Easing = z.infer<typeof EasingSchema>;
+/** Zod schema for validating {@link Keyframe} objects. */
+declare const KeyframeSchema: z.ZodObject<{
+    value: z.ZodNumber;
+    duration: z.ZodNumber;
+    easing: z.ZodOptional<z.ZodEnum<{
+        linear: "linear";
+        easeIn: "easeIn";
+        easeOut: "easeOut";
+        easeInOut: "easeInOut";
+        step: "step";
+    }>>;
+}, z.core.$strip>;
+/**
+ * A single animation keyframe with a target value, transition duration, and optional {@link Easing}.
+ *
+ * Duration of 0 creates an instant jump to the value.
+ */
+type Keyframe = z.infer<typeof KeyframeSchema>;
+/** Zod schema for validating {@link Track} objects. */
+declare const TrackSchema: z.ZodObject<{
+    featureIndex: z.ZodNumber;
+    keyframes: z.ZodArray<z.ZodObject<{
+        value: z.ZodNumber;
+        duration: z.ZodNumber;
+        easing: z.ZodOptional<z.ZodEnum<{
+            linear: "linear";
+            easeIn: "easeIn";
+            easeOut: "easeOut";
+            easeInOut: "easeInOut";
+            step: "step";
+        }>>;
+    }, z.core.$strip>>;
+    clockwise: z.ZodOptional<z.ZodBoolean>;
+    outputType: z.ZodOptional<z.ZodEnum<{
+        Vibrate: "Vibrate";
+        Rotate: "Rotate";
+        RotateWithDirection: "RotateWithDirection";
+        Oscillate: "Oscillate";
+        Constrict: "Constrict";
+        Spray: "Spray";
+        Temperature: "Temperature";
+        Led: "Led";
+        Position: "Position";
+        HwPositionWithDuration: "HwPositionWithDuration";
+    }>>;
+}, z.core.$strip>;
+/** A sequence of {@link Keyframe} values bound to a specific device feature. */
+type Track = z.infer<typeof TrackSchema>;
+/** Available built-in pattern preset names. */
+declare const PRESET_NAMES: readonly ["pulse", "wave", "ramp_up", "ramp_down", "heartbeat", "surge", "stroke"];
+/** A built-in preset pattern name from {@link PRESET_NAMES}. */
+type PresetName = (typeof PRESET_NAMES)[number];
+/** Zod schema for validating {@link PresetPattern} descriptors. */
+declare const PresetPatternSchema: z.ZodObject<{
+    type: z.ZodLiteral<"preset">;
+    preset: z.ZodEnum<{
+        pulse: "pulse";
+        wave: "wave";
+        ramp_up: "ramp_up";
+        ramp_down: "ramp_down";
+        heartbeat: "heartbeat";
+        surge: "surge";
+        stroke: "stroke";
+    }>;
+    intensity: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    loop: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
+}, z.core.$strip>;
+/**
+ * Pattern descriptor that references a built-in preset by name.
+ *
+ * Allows optional intensity scaling (0-1), speed multiplier (0.25-4x),
+ * and loop configuration.
+ */
+type PresetPattern = z.infer<typeof PresetPatternSchema>;
+/** Zod schema for validating {@link CustomPattern} descriptors. */
+declare const CustomPatternSchema: z.ZodObject<{
+    type: z.ZodLiteral<"custom">;
+    tracks: z.ZodArray<z.ZodObject<{
+        featureIndex: z.ZodNumber;
+        keyframes: z.ZodArray<z.ZodObject<{
+            value: z.ZodNumber;
+            duration: z.ZodNumber;
+            easing: z.ZodOptional<z.ZodEnum<{
+                linear: "linear";
+                easeIn: "easeIn";
+                easeOut: "easeOut";
+                easeInOut: "easeInOut";
+                step: "step";
+            }>>;
+        }, z.core.$strip>>;
+        clockwise: z.ZodOptional<z.ZodBoolean>;
+        outputType: z.ZodOptional<z.ZodEnum<{
+            Vibrate: "Vibrate";
+            Rotate: "Rotate";
+            RotateWithDirection: "RotateWithDirection";
+            Oscillate: "Oscillate";
+            Constrict: "Constrict";
+            Spray: "Spray";
+            Temperature: "Temperature";
+            Led: "Led";
+            Position: "Position";
+            HwPositionWithDuration: "HwPositionWithDuration";
+        }>>;
+    }, z.core.$strip>>;
+    intensity: z.ZodOptional<z.ZodNumber>;
+    loop: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
+}, z.core.$strip>;
+/**
+ * Pattern descriptor with user-defined keyframe tracks.
+ *
+ * Each track targets a specific feature index and contains its own keyframe sequence.
+ */
+type CustomPattern = z.infer<typeof CustomPatternSchema>;
+/**
+ * Discriminated union schema for pattern descriptors.
+ *
+ * Uses the `type` field to distinguish between preset and custom patterns.
+ */
+declare const PatternDescriptorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"preset">;
+    preset: z.ZodEnum<{
+        pulse: "pulse";
+        wave: "wave";
+        ramp_up: "ramp_up";
+        ramp_down: "ramp_down";
+        heartbeat: "heartbeat";
+        surge: "surge";
+        stroke: "stroke";
+    }>;
+    intensity: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    loop: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"custom">;
+    tracks: z.ZodArray<z.ZodObject<{
+        featureIndex: z.ZodNumber;
+        keyframes: z.ZodArray<z.ZodObject<{
+            value: z.ZodNumber;
+            duration: z.ZodNumber;
+            easing: z.ZodOptional<z.ZodEnum<{
+                linear: "linear";
+                easeIn: "easeIn";
+                easeOut: "easeOut";
+                easeInOut: "easeInOut";
+                step: "step";
+            }>>;
+        }, z.core.$strip>>;
+        clockwise: z.ZodOptional<z.ZodBoolean>;
+        outputType: z.ZodOptional<z.ZodEnum<{
+            Vibrate: "Vibrate";
+            Rotate: "Rotate";
+            RotateWithDirection: "RotateWithDirection";
+            Oscillate: "Oscillate";
+            Constrict: "Constrict";
+            Spray: "Spray";
+            Temperature: "Temperature";
+            Led: "Led";
+            Position: "Position";
+            HwPositionWithDuration: "HwPositionWithDuration";
+        }>>;
+    }, z.core.$strip>>;
+    intensity: z.ZodOptional<z.ZodNumber>;
+    loop: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
+}, z.core.$strip>], "type">;
+/**
+ * Pattern descriptor that can be either preset-based or custom-defined.
+ */
+type PatternDescriptor = z.infer<typeof PatternDescriptorSchema>;
+/**
+ * Client interface consumed by {@link PatternEngine} for {@link PatternDevice} access and event subscription.
+ *
+ * Decouples the engine from the full buttplug client, requiring only device
+ * lookup and disconnect/removal event hooks.
+ */
+interface PatternEngineClient {
+    /**
+     * Retrieves a {@link PatternDevice} by its server-assigned index.
+     *
+     * @param index - The device index to look up
+     * @returns The device if found, or undefined
+     */
+    getDevice(index: number): PatternDevice | undefined;
+    /**
+     * Subscribes to the client disconnected event.
+     *
+     * @param event - The event name
+     * @param handler - Callback invoked on disconnect
+     * @returns Unsubscribe function
+     */
+    on(event: "disconnected", handler: (data: {
+        reason?: string;
+    }) => void): () => void;
+    /**
+     * Subscribes to the device removed event.
+     *
+     * @param event - The event name
+     * @param handler - Callback invoked when a {@link PatternDevice} is removed
+     * @returns Unsubscribe function
+     */
+    on(event: "deviceRemoved", handler: (data: {
+        device: PatternDevice;
+    }) => void): () => void;
+}
+/** Reason a pattern was stopped, used in {@link PatternPlayOptions.onStop} callbacks. */
+type StopReason = "manual" | "complete" | "timeout" | "error" | "disconnect" | "deviceRemoved";
+/**
+ * Unified options for controlling pattern playback behavior.
+ *
+ * Combines device targeting, preset tuning, loop control, timeout,
+ * and lifecycle callbacks into a single options object.
+ */
+interface PatternPlayOptions {
+    /** Target a specific feature index instead of auto-resolving. */
+    featureIndex?: number;
+    /** Intensity scaling (0-1). Applied to preset and custom patterns. */
+    intensity?: number;
+    /** Loop behavior override. */
+    loop?: boolean | number;
+    /** Called when the pattern completes all loops naturally. */
+    onComplete?: (patternId: string) => void;
+    /** Called whenever the pattern stops for any {@link StopReason}. */
+    onStop?: (patternId: string, reason: StopReason) => void;
+    /** Speed multiplier (0.25-4x). Only applies to preset shorthand. */
+    speed?: number;
+    /** Maximum playback duration in milliseconds before auto-stop. */
+    timeout?: number;
+}
+/**
+ * @deprecated Use {@link PatternPlayOptions} instead.
+ */
+type PlayOptions = PatternPlayOptions;
+/**
+ * Read-only snapshot of a running pattern, returned by {@link PatternEngine.list}.
+ */
+interface PatternInfo {
+    /** The original {@link PatternDescriptor} used to create this pattern. */
+    readonly descriptor: PatternDescriptor;
+    /** Index of the device this pattern targets. */
+    readonly deviceIndex: number;
+    /** Milliseconds elapsed since playback began. */
+    readonly elapsed: number;
+    /** Feature indices being driven by this pattern. */
+    readonly featureIndices: number[];
+    /** Unique pattern instance identifier. */
+    readonly id: string;
+    /** Timestamp (from `performance.now()`) when playback began. */
+    readonly startedAt: number;
+}
+/**
+ * Metadata describing a built-in preset pattern.
+ */
+interface PresetInfo {
+    /** {@link OutputType} values this preset is designed for. */
+    readonly compatibleOutputTypes: OutputType[];
+    /** Whether the preset loops by default. */
+    readonly defaultLoop: boolean;
+    /** Human-readable description of the pattern's behavior. */
+    readonly description: string;
+    /** Preset name identifier. */
+    readonly name: string;
+}
+
+type EasingName = Easing;
+/** A function that maps a normalized time value (0-1) to an eased output value. */
+type EasingFunction = (t: number) => number;
+/**
+ * Lookup table mapping {@link EasingName} identifiers to their easing functions.
+ *
+ * All functions use cubic curves except `step` (discrete) and `linear` (identity).
+ */
+declare const EASING_FUNCTIONS: Record<EasingName, EasingFunction>;
+
+/**
+ * Orchestrates pattern playback on buttplug devices using tick-based keyframe scheduling.
+ *
+ * Manages the lifecycle of active patterns including loop handling, drift-corrected
+ * tick scheduling, deduplication of redundant commands, and automatic cleanup on
+ * disconnect or device removal.
+ */
+declare class PatternEngine {
+    #private;
+    /**
+     * @param client - Client providing device access and event hooks
+     * @param options - Optional configuration for default timeout behavior
+     */
+    constructor(client: PatternEngineClient, options?: {
+        defaultTimeout?: number;
+    });
+    /**
+     * Starts playing a preset pattern on a device by name.
+     *
+     * @param device - Target device or device index
+     * @param preset - Built-in preset name (e.g. "wave", "pulse")
+     * @param options - Playback options including intensity, speed, loop, timeout, and callbacks
+     * @returns Unique pattern instance ID for later control
+     * @throws {DeviceError} If the engine is disposed, device not found, or no compatible features
+     */
+    play(device: PatternDevice | number, preset: PresetName, options?: PatternPlayOptions): Promise<string>;
+    /**
+     * Starts playing a custom pattern defined by keyframe tracks.
+     *
+     * @param device - Target device or device index
+     * @param tracks - Array of {@link Track} definitions with keyframes bound to feature indices
+     * @param options - Playback options including intensity, loop, timeout, and callbacks
+     * @returns Unique pattern instance ID for later control
+     * @throws {DeviceError} If the engine is disposed, device not found, or no compatible features
+     */
+    play(device: PatternDevice | number, tracks: Track[], options?: PatternPlayOptions): Promise<string>;
+    /**
+     * Starts playing a pattern from a full {@link PatternDescriptor}.
+     *
+     * @param device - Target device or device index
+     * @param descriptor - Full pattern descriptor (preset or custom)
+     * @param options - Playback options including timeout and callbacks
+     * @returns Unique pattern instance ID for later control
+     * @throws {DeviceError} If the engine is disposed, device not found, or no compatible features
+     */
+    play(device: PatternDevice | number, descriptor: PatternDescriptor, options?: PatternPlayOptions): Promise<string>;
+    /**
+     * Stops a specific pattern by its ID.
+     *
+     * No-op if the pattern ID is not found (already stopped or never started).
+     *
+     * @param patternId - The pattern instance ID returned by {@link play}
+     */
+    stop(patternId: string): Promise<void>;
+    /**
+     * Stops all active patterns.
+     *
+     * @returns Number of patterns that were stopped
+     */
+    stopAll(): number;
+    /**
+     * Stops all active patterns targeting a specific device.
+     *
+     * @param deviceIndex - The device index to stop patterns for
+     * @returns Number of patterns that were stopped
+     */
+    stopByDevice(deviceIndex: number): number;
+    /**
+     * Returns a snapshot of all active patterns.
+     *
+     * @returns Array of {@link PatternInfo} snapshots
+     */
+    list(): PatternInfo[];
+    /**
+     * Returns metadata for all available built-in presets.
+     *
+     * @returns Array of {@link PresetInfo} descriptors
+     */
+    listPresets(): PresetInfo[];
+    /**
+     * Disposes the engine, stopping all patterns and unsubscribing from client events.
+     *
+     * Subsequent calls to {@link play} will throw. Idempotent.
+     */
+    dispose(): void;
+}
+
+/**
+ * Internal definition of a preset pattern, including its keyframe tracks
+ * and compatible output types.
+ */
+interface PresetDefinition {
+    /** Human-readable description of the pattern's behavior. */
+    readonly description: string;
+    /** Whether this preset loops by default. */
+    readonly loop: boolean;
+    /** {@link OutputType} values this preset is compatible with. */
+    readonly outputTypes: OutputType[];
+    /** Keyframe sequences for the pattern. Features are assigned tracks via round-robin when there are more features than tracks. */
+    readonly tracks: Keyframe[][];
+}
+/**
+ * Built-in pattern presets keyed by {@link PresetName}.
+ *
+ * Each preset defines keyframe tracks, compatible output types, and default loop behavior.
+ * Presets are resolved into {@link ResolvedTrack} arrays by the track resolver.
+ */
+declare const PRESETS: Record<PresetName, PresetDefinition>;
+/**
+ * Returns metadata for all available preset patterns.
+ *
+ * @returns Array of {@link PresetInfo} with name, description, compatible types, and loop defaults
+ */
+declare function getPresetInfo(): PresetInfo[];
+
+export { ButtplugClient, type ButtplugClientOptions, ButtplugError, type ClientEventMap, type ClientMessage, ClientMessageSchema, ConnectionError, type CustomPattern, DEFAULT_CLIENT_NAME, DEFAULT_PING_INTERVAL, DEFAULT_REQUEST_TIMEOUT, Device, DeviceError, type DeviceFeatures, DeviceFeaturesSchema, type DeviceMessageSender, type DeviceOptions, type DeviceOutputOptions, type DeviceStopOptions, EASING_FUNCTIONS, EASING_VALUES, type Easing, type EasingFunction, type EasingName, ErrorCode, type FeatureValue, FeatureValueSchema, HandshakeError, type HwPositionOutputData, HwPositionOutputDataSchema, INPUT_TYPES, INPUT_TYPE_VALUES, type InputCommandType, InputCommandTypeSchema, type InputData, InputDataSchema, type InputFeature, InputFeatureSchema, type InputReading, InputReadingSchema, type InputType, InputTypeSchema, type Keyframe, KeyframeSchema, type Logger, MAX_MESSAGE_ID, OUTPUT_TYPES, OUTPUT_TYPE_VALUES, type OutputCommand, OutputCommandSchema, type OutputFeature, OutputFeatureSchema, type OutputType, OutputTypeSchema, PRESETS, PRESET_NAMES, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, type PatternDescriptor, PatternDescriptorSchema, type PatternDevice, PatternEngine, type PatternEngineClient, type PatternInfo, type PatternPlayOptions, PingManager, type PingOptions, type PlayOptions, type PositionValue, PositionValueSchema, type PresetInfo, type PresetName, type PresetPattern, ProtocolError, ReconnectDefaults, ReconnectHandler, type ReconnectOptions, type RotateWithDirectionOutputData, RotateWithDirectionOutputDataSchema, type RotationValue, RotationValueSchema, type ScalarOutputData, type SensorCallback, type SensorValue, SensorValueSchema, type ServerInfo, ServerInfoSchema, type ServerMessage, ServerMessageSchema, type SignedScalarOutputData, SignedScalarOutputDataSchema, type StopReason, TimeoutError, type Track, type Transport, type TransportEvents, type TransportOptions, type TransportState, type TypedEmitter, type UnsignedScalarOutputData, UnsignedScalarOutputDataSchema, WebSocketTransport, type WebSocketTransportOptions, consoleLogger, formatError, getLogger, getPresetInfo, noopLogger, runWithLogger };