@voltras/node-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voltra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# @voltras/node-sdk
+
+SDK for connecting to and controlling Voltra fitness devices.
+
+[![npm version](https://img.shields.io/npm/v/@voltras/node-sdk.svg)](https://www.npmjs.com/package/@voltras/node-sdk)
+[![CI](https://github.com/voltra/node-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/voltra/node-sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Simple API**: `VoltraManager` handles discovery, returns `VoltraClient` for device control
+- **Cross-platform**: Web browsers, Node.js, and React Native
+- **Multi-device**: Connect to multiple devices simultaneously
+- **React hooks**: Clean `useVoltraScanner` and `useVoltraDevice` hooks
+- **TypeScript**: Full type definitions included
+- **Real-time telemetry**: Stream position, velocity, and force data
+
+## Installation
+
+```bash
+npm install @voltras/node-sdk
+```
+
+### Platform dependencies
+
+| Platform | Additional Install |
+|----------|-------------------|
+| React Native | `npm install react-native-ble-plx` |
+| Node.js | `npm install webbluetooth` |
+| Web browsers | None (uses Web Bluetooth API) |
+
+## Quick Start
+
+### Web / Node.js
+
+```typescript
+import { VoltraManager } from '@voltras/node-sdk';
+
+// Create manager (auto-detects platform)
+const manager = new VoltraManager();
+
+// Scan and connect to first device
+const client = await manager.connectFirst();
+
+// Or connect by name
+const client = await manager.connectByName('VTR-123456');
+
+// Control the device
+await client.setWeight(50);
+
+client.onFrame((frame) => {
+  console.log('Position:', frame.position, 'Velocity:', frame.velocity);
+});
+
+await client.startRecording();
+// ... workout ...
+await client.stopRecording();
+
+// Cleanup
+manager.dispose();
+```
+
+### React Native
+
+```typescript
+import { VoltraManager } from '@voltras/node-sdk';
+
+// Specify native platform
+const manager = VoltraManager.forNative();
+// or: new VoltraManager({ platform: 'native' })
+
+// Rest of the API is identical
+const client = await manager.connectFirst();
+```
+
+### React Hooks
+
+```tsx
+import { VoltraManager } from '@voltras/node-sdk';
+import { useVoltraScanner, useVoltraDevice } from '@voltras/node-sdk/react';
+
+function WorkoutScreen() {
+  const manager = useMemo(() => VoltraManager.forNative(), []);
+  const [client, setClient] = useState<VoltraClient | null>(null);
+
+  // Scanner state
+  const { devices, isScanning, scan } = useVoltraScanner(manager);
+
+  // Device state
+  const { connectionState, currentFrame, isRecording } = useVoltraDevice(client);
+
+  const handleConnect = async (device: DiscoveredDevice) => {
+    const connected = await manager.connect(device);
+    setClient(connected);
+  };
+
+  return (
+    <View>
+      <Button onPress={() => scan()}>
+        {isScanning ? 'Scanning...' : 'Scan'}
+      </Button>
+
+      {devices.map((device) => (
+        <Button key={device.id} onPress={() => handleConnect(device)}>
+          {device.name}
+        </Button>
+      ))}
+
+      {connectionState === 'connected' && (
+        <Text>Position: {currentFrame?.position}</Text>
+      )}
+    </View>
+  );
+}
+```
+
+## Multi-Device
+
+```typescript
+const manager = new VoltraManager();
+
+// Listen for device events
+manager.onDeviceConnected((client, deviceId, deviceName) => {
+  console.log('Connected:', deviceName);
+  client.onFrame((frame) => console.log(`[${deviceName}]`, frame.position));
+});
+
+// Connect to multiple devices
+const devices = await manager.scan();
+await manager.connect(devices[0]);
+await manager.connect(devices[1]);
+
+// Access individual clients
+const client = manager.getClient(devices[0].id);
+await client?.setWeight(50);
+
+// Or get all clients
+for (const client of manager.getAllClients()) {
+  await client.startRecording();
+}
+```
+
+## API Reference
+
+### VoltraManager
+
+Main entry point for the SDK.
+
+```typescript
+const manager = new VoltraManager(options?);
+// or
+const manager = VoltraManager.forWeb();
+const manager = VoltraManager.forNode();
+const manager = VoltraManager.forNative();
+```
+
+**Methods:**
+- `scan(options?)` - Scan for Voltra devices
+- `connect(device)` - Connect and return a VoltraClient
+- `connectFirst(options?)` - Connect to first available device
+- `connectByName(name, options?)` - Scan + connect by device name
+- `getClient(deviceId)` - Get connected client by ID
+- `getAllClients()` - Get all connected clients
+- `disconnect(deviceId)` - Disconnect specific device
+- `disconnectAll()` - Disconnect all devices
+- `dispose()` - Clean up resources
+
+### VoltraClient
+
+Controls a single connected device.
+
+**Methods:**
+- `setWeight(lbs)` - Set weight (5-200 in increments of 5)
+- `setChains(lbs)` - Set chains (0-100)
+- `setEccentric(percent)` - Set eccentric adjustment (-195 to +195)
+- `startRecording()` - Start recording
+- `stopRecording()` - Stop recording
+- `onFrame(callback)` - Subscribe to telemetry frames
+- `disconnect()` - Disconnect from device
+
+**Properties:**
+- `connectionState` - 'disconnected' | 'connecting' | 'authenticating' | 'connected'
+- `isConnected` - Whether connected
+- `settings` - Current device settings
+- `recordingState` - 'idle' | 'preparing' | 'ready' | 'active' | 'stopping'
+- `isRecording` - Whether recording
+
+### TelemetryFrame
+
+```typescript
+interface TelemetryFrame {
+  sequence: number;   // Packet sequence number
+  timestamp: number;  // Unix ms when received
+  phase: number;      // Movement phase (see MovementPhase)
+  position: number;   // Position (0-600 raw)
+  velocity: number;   // Velocity (raw value)
+  force: number;      // Force (signed value)
+}
+```
+
+### React Hooks
+
+```typescript
+import { useVoltraScanner, useVoltraDevice } from '@voltras/node-sdk/react';
+
+// Scanner state
+const { devices, isScanning, scan, error, clear } = useVoltraScanner(manager);
+
+// Device state
+const {
+  connectionState,
+  isConnected,
+  recordingState,
+  isRecording,
+  currentFrame,
+  settings,
+  error,
+} = useVoltraDevice(client);
+```
+
+## Error Handling
+
+```typescript
+import {
+  VoltraSDKError,
+  ConnectionError,
+  AuthenticationError,
+  NotConnectedError,
+} from '@voltras/node-sdk';
+
+try {
+  await manager.connectByName('VTR-123');
+} catch (error) {
+  if (error instanceof ConnectionError) {
+    console.log('Connection failed:', error.code);
+  }
+}
+```
+
+## Examples
+
+See the [examples](./examples) directory:
+
+- [Node.js](./examples/node) - CLI examples
+- [Web Browser](./examples/web) - Interactive demo
+- [React Native](./examples/react-native) - Expo app
+
+## Documentation
+
+### Getting Started
+
+Step-by-step setup guides for each platform:
+
+- [Node.js](./docs/getting-started/node.md) - Prerequisites, setup, running examples
+- [Web Browser](./docs/getting-started/web.md) - Browser requirements, HTTPS, Vite setup
+- [React Native](./docs/getting-started/react-native.md) - Expo, permissions, development builds
+
+### Concepts
+
+Technical deep-dives:
+
+- [Bluetooth Protocol](./docs/concepts/bluetooth-protocol.md) - Voltra BLE protocol, commands, telemetry format
+- [Platform Adapters](./docs/concepts/platform-adapters.md) - Native vs Web vs Node.js differences
+
+### Other
+
+- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+- [Roadmap](./docs/roadmap/) - Planned features (ReplayBLEAdapter, etc.)
+
+## License
+
+MIT - see [LICENSE](./LICENSE)

package/dist/cjs/bluetooth/adapters/base.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * BaseBLEAdapter
+ *
+ * Abstract base class for all BLE adapters. Provides shared implementation
+ * for connection state management and callback registration/notification.
+ *
+ * Subclasses implement the platform-specific BLE operations:
+ * - NativeBLEAdapter: react-native-ble-plx for iOS/Android
+ * - WebBLEAdapter: Web Bluetooth API for browsers
+ * - NodeBLEAdapter: webbluetooth npm for Node.js
+ * - ReplayBLEAdapter: Playback for testing/demos
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseBLEAdapter = void 0;
+/**
+ * Abstract base class implementing shared BLE adapter functionality.
+ *
+ * Provides:
+ * - Connection state management with change notifications
+ * - Notification callback registration (supports multiple listeners)
+ * - State callback registration (supports multiple listeners)
+ * - Protected utilities for subclasses to emit events
+ */
+class BaseBLEAdapter {
+    constructor() {
+        /** Current connection state */
+        this.connectionState = 'disconnected';
+        /** Registered notification callbacks */
+        this.notificationCallbacks = [];
+        /** Registered connection state callbacks */
+        this.stateCallbacks = [];
+    }
+    // ===========================================================================
+    // BLEAdapter interface - implemented
+    // ===========================================================================
+    /**
+     * Get the current connection state.
+     */
+    getConnectionState() {
+        return this.connectionState;
+    }
+    /**
+     * Check if currently connected to a device.
+     */
+    isConnected() {
+        return this.connectionState === 'connected';
+    }
+    /**
+     * Register a callback for notifications from the device.
+     * @param callback Function called with notification data
+     * @returns Unsubscribe function
+     */
+    onNotification(callback) {
+        this.notificationCallbacks.push(callback);
+        return () => {
+            const index = this.notificationCallbacks.indexOf(callback);
+            if (index >= 0) {
+                this.notificationCallbacks.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Register a callback for connection state changes.
+     * @param callback Function called when state changes
+     * @returns Unsubscribe function
+     */
+    onConnectionStateChange(callback) {
+        this.stateCallbacks.push(callback);
+        return () => {
+            const index = this.stateCallbacks.indexOf(callback);
+            if (index >= 0) {
+                this.stateCallbacks.splice(index, 1);
+            }
+        };
+    }
+    // ===========================================================================
+    // Protected utilities for subclasses
+    // ===========================================================================
+    /**
+     * Set connection state and notify all registered callbacks.
+     * Only notifies if state actually changed.
+     *
+     * @param state New connection state
+     */
+    setConnectionState(state) {
+        if (this.connectionState !== state) {
+            this.connectionState = state;
+            for (const callback of this.stateCallbacks) {
+                try {
+                    callback(state);
+                }
+                catch (e) {
+                    console.error('[BaseBLEAdapter] State callback error:', e);
+                }
+            }
+        }
+    }
+    /**
+     * Emit notification data to all registered callbacks.
+     *
+     * @param data Notification data to emit
+     */
+    emitNotification(data) {
+        for (const callback of this.notificationCallbacks) {
+            try {
+                callback(data);
+            }
+            catch (e) {
+                console.error('[BaseBLEAdapter] Notification callback error:', e);
+            }
+        }
+    }
+}
+exports.BaseBLEAdapter = BaseBLEAdapter;
+//# sourceMappingURL=base.js.map

package/dist/cjs/bluetooth/adapters/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/bluetooth/adapters/base.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAWH;;;;;;;;GAQG;AACH,MAAsB,cAAc;IAApC;QACE,+BAA+B;QACrB,oBAAe,GAAoB,cAAc,CAAC;QAE5D,wCAAwC;QAC9B,0BAAqB,GAA2B,EAAE,CAAC;QAE7D,4CAA4C;QAClC,mBAAc,GAA8B,EAAE,CAAC;IAoH3D,CAAC;IAlHC,8EAA8E;IAC9E,qCAAqC;IACrC,8EAA8E;IAE9E;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,eAAe,KAAK,WAAW,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,QAA8B;QAC3C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,OAAO,GAAG,EAAE;YACV,MAAM,KAAK,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC3D,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,uBAAuB,CAAC,QAAiC;QACvD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE;YACV,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACvC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IA+BD,8EAA8E;IAC9E,qCAAqC;IACrC,8EAA8E;IAE9E;;;;;OAKG;IACO,kBAAkB,CAAC,KAAsB;QACjD,IAAI,IAAI,CAAC,eAAe,KAAK,KAAK,EAAE,CAAC;YACnC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;YAC7B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBAC3C,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,CAAC,CAAC,CAAC;gBAC7D,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACO,gBAAgB,CAAC,IAAgB;QACzC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAClD,IAAI,CAAC;gBACH,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,+CAA+C,EAAE,CAAC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AA5HD,wCA4HC"}

package/dist/cjs/bluetooth/adapters/index.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * BLE Abstraction Layer
+ *
+ * Provides a unified interface for BLE communication across platforms:
+ * - Native (iOS/Android): react-native-ble-plx
+ * - Browser: Web Bluetooth API
+ * - Node.js: webbluetooth npm package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeBLEAdapter = exports.NodeBLEAdapter = exports.WebBLEAdapter = void 0;
+exports.createBLEAdapter = createBLEAdapter;
+// Platform adapters
+var web_1 = require("./web");
+Object.defineProperty(exports, "WebBLEAdapter", { enumerable: true, get: function () { return web_1.WebBLEAdapter; } });
+var node_1 = require("./node");
+Object.defineProperty(exports, "NodeBLEAdapter", { enumerable: true, get: function () { return node_1.NodeBLEAdapter; } });
+var native_1 = require("./native");
+Object.defineProperty(exports, "NativeBLEAdapter", { enumerable: true, get: function () { return native_1.NativeBLEAdapter; } });
+const web_2 = require("./web");
+const node_2 = require("./node");
+/**
+ * Detect if running in Node.js environment.
+ */
+function isNodeEnvironment() {
+    return (typeof process !== 'undefined' && process.versions != null && process.versions.node != null);
+}
+/**
+ * Detect if running in browser environment.
+ */
+function isBrowserEnvironment() {
+    return (typeof window !== 'undefined' &&
+        typeof document !== 'undefined' &&
+        typeof navigator !== 'undefined');
+}
+/**
+ * Create a BLE adapter based on the current environment.
+ *
+ * Environment detection:
+ * - Web browser: WebBLEAdapter (Web Bluetooth API)
+ * - Node.js: NodeBLEAdapter (webbluetooth package)
+ *
+ * NOTE: For React Native, import and instantiate NativeBLEAdapter directly.
+ * This factory is for web/Node.js environments only.
+ *
+ * @param config Adapter configuration including BLE service UUIDs
+ * @returns BLEAdapter instance appropriate for the current environment
+ */
+function createBLEAdapter(config) {
+    if (isNodeEnvironment() && !isBrowserEnvironment()) {
+        return new node_2.NodeBLEAdapter({ ble: config.ble });
+    }
+    if (isBrowserEnvironment()) {
+        return new web_2.WebBLEAdapter({ ble: config.ble });
+    }
+    throw new Error('Unknown environment. For React Native, import NativeBLEAdapter directly from @voltras/node-sdk/react-native');
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/bluetooth/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/bluetooth/adapters/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAkEH,4CAYC;AAjED,oBAAoB;AACpB,6BAAsC;AAA7B,oGAAA,aAAa,OAAA;AACtB,+BAAgF;AAAvE,sGAAA,cAAc,OAAA;AACvB,mCAAsE;AAA7D,0GAAA,gBAAgB,OAAA;AAMzB,+BAAsC;AACtC,iCAAwC;AAUxC;;GAEG;AACH,SAAS,iBAAiB;IACxB,OAAO,CACL,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,QAAQ,IAAI,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAC5F,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB;IAC3B,OAAO,CACL,OAAO,MAAM,KAAK,WAAW;QAC7B,OAAO,QAAQ,KAAK,WAAW;QAC/B,OAAO,SAAS,KAAK,WAAW,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB,CAAC,MAA8B;IAC7D,IAAI,iBAAiB,EAAE,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;QACnD,OAAO,IAAI,qBAAc,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,oBAAoB,EAAE,EAAE,CAAC;QAC3B,OAAO,IAAI,mBAAa,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,IAAI,KAAK,CACb,6GAA6G,CAC9G,CAAC;AACJ,CAAC"}