wvke-sdk 1.0.20260422

package/README.md

@@ -0,0 +1,180 @@
+# wvke-sdk
+
+wvke-sdk is a JavaScript and TypeScript SDK for gaming peripherals. It is built on WebHID and provides keyboard and mouse APIs for device discovery, initialization, configuration, lighting, and performance features.
+
+## Website and Docs
+
+- Website: https://www.wvke.top/
+- Documentation: https://www.wvke.top/docs/
+
+## Version
+
+Current package version: `1.0.20260422`
+
+## What's New in 1.0.20260422
+
+- Fixed the npm package README publishing flow so the published README now uses `src/lib/README.md` as the single source of truth.
+- Cleaned up the package README structure for npm publishing and aligned package preparation with the `npm-package` directory workflow.
+
+## What's New in 1.0.6
+
+- Synced the DKS advanced-key API so the `task` parameter now uses the final 4-segment format only.
+- Renamed DKS debug-tool fields from `bits` to `trps` and documented the 7-bit trigger order.
+- Updated Chinese and English higherKey documentation with the trps bit mapping and refreshed website release content.
+
+## Install
+
+```bash
+npm install wvke-sdk
+```
+
+## Runtime Requirements
+
+- A modern browser with WebHID support.
+- A user gesture before requesting device access.
+- HTTPS or localhost during development and testing.
+
+## Main Exports
+
+```javascript
+import ServiceKeyboard, {
+  ServiceKeyboard,
+  ServiceMouse,
+  versionManager,
+  logger,
+  performanceMonitor
+} from 'wvke-sdk'
+```
+
+- `ServiceKeyboard`: keyboard SDK service.
+- `ServiceMouse`: mouse SDK service.
+- `versionManager`: SDK version and compatibility helper.
+- `logger`: runtime logger.
+- `performanceMonitor`: operation and connection metrics helper.
+
+## Keyboard Quick Start
+
+```javascript
+import { ServiceKeyboard } from 'wvke-sdk'
+
+const keyboard = new ServiceKeyboard()
+const { code, devices } = await keyboard.getDevices()
+
+if (code !== 0 || devices.length === 0) {
+  throw new Error('No keyboard devices found')
+}
+
+await keyboard.init(devices[0].id)
+
+const info = await keyboard.getDevicesInfo()
+console.log(info)
+```
+
+## Mouse Quick Start
+
+```javascript
+import { ServiceMouse } from 'wvke-sdk'
+
+const mouse = new ServiceMouse()
+const devices = await mouse.getDevices()
+
+if (devices.length === 0) {
+  throw new Error('No mouse devices found')
+}
+
+await mouse.init(devices[0].id)
+
+const dpi = await mouse.getDPI()
+console.log(dpi)
+```
+
+## Examples
+
+### Read current keyboard config and polling rate
+
+```javascript
+import { ServiceKeyboard } from 'wvke-sdk'
+
+const keyboard = new ServiceKeyboard()
+const { code, devices } = await keyboard.getDevices()
+
+if (code !== 0 || devices.length === 0) {
+  throw new Error('No keyboard devices found')
+}
+
+const initResult = await keyboard.init(devices[0].id)
+
+if (initResult.code !== 0) {
+  throw new Error(initResult.info || 'Keyboard initialization failed')
+}
+
+const currentConfig = await keyboard.getConfig()
+const pollingRate = await keyboard.getRateOfReturn()
+
+console.log(currentConfig)
+console.log(pollingRate)
+```
+
+### Set keyboard backlight base config
+
+```javascript
+await keyboard.setLightingBase({
+  data: {
+    mode: 2,
+    childMode: 1,
+    luminance: 3,
+    speed: 4
+  }
+})
+```
+
+### Read custom keyboard backlight with live reports
+
+```javascript
+const handleReport = (payload) => {
+  console.log('keyboardBacklightCustomReport', payload)
+}
+
+keyboard.on('keyboardBacklightCustomReport', handleReport)
+
+const snapshot = await keyboard.getKeyboardBacklightCustom()
+console.log(snapshot)
+
+const heartbeatId = setInterval(() => {
+  keyboard.getKeyboardBacklightCustom().catch(console.error)
+}, 5000)
+
+keyboard.off('keyboardBacklightCustomReport', handleReport)
+clearInterval(heartbeatId)
+```
+
+### Read and update mouse DPI
+
+```javascript
+import { ServiceMouse } from 'wvke-sdk'
+
+const mouse = new ServiceMouse()
+const devices = await mouse.getDevices()
+
+if (devices.length === 0) {
+  throw new Error('No mouse devices found')
+}
+
+await mouse.init(devices[0].id)
+
+const currentDpi = await mouse.getDPI()
+await mouse.setDPI(1600)
+
+console.log(currentDpi)
+```
+
+## TypeScript
+
+Type declarations are bundled with the package.
+
+## Notes
+
+- `ServiceKeyboard.getDevices()` returns `{ code, devices }`.
+- `ServiceMouse.getDevices()` returns a device array directly.
+- Keyboard custom backlight and logo custom lighting support real-time report events and heartbeat-based refresh.
+- The package README published to npm is generated from this file via `npm run package:prepare`.