From d64cb321f542323b9ecd41ceff3424ea6f388fc2 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Thu, 21 Aug 2025 00:27:54 -0500
Subject: [PATCH 1/4] Add comprehensive GitHub Copilot instructions for
node-switchbot repository (#300)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
This PR adds a comprehensive `.github/copilot-instructions.md` file that
provides GitHub Copilot coding agents with detailed instructions on how
to work effectively in the node-switchbot codebase.
## Key Features
**Validated Commands and Timing**: Every command has been tested from a
clean environment with actual timing measurements:
- `npm install`: ~5-25 seconds (varies by cache)
- `npm run build`: ~5 seconds (TypeScript compilation)
- `npm run test`: ~1 second (12 tests)
- `npm run lint`: ~3 seconds (ESLint validation)
**Platform-Specific Requirements**: Clear documentation of constraints:
- BLE functionality requires Linux-based OS only (Raspbian, Ubuntu,
etc.)
- Windows and macOS are NOT supported for BLE operations
- Node.js versions: ^20, ^22, or ^24 required
- ES Modules: Project uses `"type": "module"`
**Development Workflow**: Step-by-step instructions for common tasks:
- Bootstrap and setup procedures
- Build, test, and lint validation cycles
- Adding new device support
- Working with both BLE and OpenAPI interfaces
**Manual Validation Scenarios**: Specific tests to run after making
changes:
```javascript
// Basic functionality validation
const { SwitchBotBLE, SwitchBotOpenAPI } = require('./dist/index.js');
const ble = new SwitchBotBLE(); // Should not throw
const api = new SwitchBotOpenAPI('test', 'test'); // Should not throw
```
**Timeout Warnings**: Explicit "NEVER CANCEL" warnings with timeout
recommendations for all build operations to prevent premature
cancellation of long-running commands.
## Project Structure Documentation
The instructions include comprehensive information about:
- Source code organization (`src/switchbot-ble.ts`,
`src/switchbot-openapi.ts`, device classes)
- Configuration files (TypeScript, ESLint, package.json)
- Build output structure (`dist/` directory)
- Documentation generation (TypeDoc)
## Validation Completed
All instructions have been thoroughly validated by:
- Following step-by-step procedures from a clean environment
- Testing basic functionality scenarios
- Verifying ES module imports work correctly
- Confirming full development workflow chain
- Measuring actual timing for all operations
The instructions follow the required imperative tone ("Run [this
command]", "Do not do [this]") and provide exhaustive guidance for
GitHub Copilot agents to work effectively in this TypeScript Node.js
library for controlling SwitchBot devices via Bluetooth Low Energy and
OpenAPI.
Fixes #299.
---
💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: donavanbecker <9875439+donavanbecker@users.noreply.github.com>
---
.github/copilot-instructions.md | 165 ++++++++++++++++++
docs/classes/Advertising.html | 8 +-
docs/classes/SwitchBotBLE.html | 16 +-
docs/classes/SwitchBotOpenAPI.html | 14 +-
docs/classes/SwitchbotDevice.html | 24 +--
docs/classes/WoBlindTilt.html | 42 ++---
docs/classes/WoBulb.html | 38 ++--
docs/classes/WoCeilingLight.html | 44 ++---
docs/classes/WoContact.html | 26 +--
docs/classes/WoCurtain.html | 36 ++--
docs/classes/WoHand.html | 36 ++--
docs/classes/WoHub2.html | 26 +--
docs/classes/WoHumi.html | 40 ++---
docs/classes/WoHumi2.html | 40 ++---
docs/classes/WoIOSensorTH.html | 26 +--
docs/classes/WoKeypad.html | 26 +--
docs/classes/WoLeak.html | 26 +--
docs/classes/WoPlugMiniJP.html | 36 ++--
docs/classes/WoPlugMiniUS.html | 36 ++--
docs/classes/WoPresence.html | 26 +--
docs/classes/WoRelaySwitch1.html | 30 ++--
docs/classes/WoRelaySwitch1PM.html | 30 ++--
docs/classes/WoRemote.html | 26 +--
docs/classes/WoSensorTH.html | 24 +--
docs/classes/WoSensorTHPlus.html | 24 +--
docs/classes/WoSensorTHPro.html | 24 +--
docs/classes/WoSensorTHProCO2.html | 24 +--
docs/classes/WoSmartLock.html | 46 ++---
docs/classes/WoSmartLockPro.html | 46 ++---
docs/classes/WoStrip.html | 40 ++---
docs/enums/LogLevel.html | 4 +-
docs/enums/SwitchBotBLEModel.html | 4 +-
docs/enums/SwitchBotBLEModelFriendlyName.html | 4 +-
docs/enums/SwitchBotBLEModelName.html | 4 +-
docs/enums/SwitchBotModel.html | 4 +-
docs/interfaces/AdvertisementData.html | 4 +-
docs/interfaces/Chars.html | 4 +-
docs/interfaces/ErrorObject.html | 4 +-
docs/interfaces/NobleTypes.html | 4 +-
docs/interfaces/Params.html | 4 +-
docs/interfaces/Rule.html | 4 +-
docs/interfaces/ServiceData.html | 4 +-
docs/interfaces/SwitchBotBLEDevice.html | 4 +-
docs/interfaces/WebhookDetail.html | 4 +-
docs/interfaces/ad.html | 4 +-
docs/interfaces/body.html | 4 +-
docs/interfaces/bodyChange.html | 4 +-
docs/interfaces/deleteWebhookResponse.html | 4 +-
docs/interfaces/device.html | 4 +-
docs/interfaces/deviceList.html | 4 +-
docs/interfaces/deviceStatus.html | 4 +-
docs/interfaces/deviceStatusRequest.html | 4 +-
docs/interfaces/deviceWebhook.html | 4 +-
docs/interfaces/deviceWebhookContext.html | 4 +-
docs/interfaces/devices.html | 4 +-
docs/interfaces/infraredRemoteList.html | 4 +-
docs/interfaces/irdevice.html | 4 +-
docs/interfaces/pushResponse.html | 4 +-
docs/interfaces/queryWebhookResponse.html | 4 +-
docs/interfaces/setupWebhookResponse.html | 4 +-
docs/interfaces/switchbot.html | 4 +-
docs/interfaces/updateWebhookResponse.html | 4 +-
docs/interfaces/webhookRequest.html | 4 +-
docs/types/MacAddress.html | 2 +-
docs/types/batteryCirculatorFan.html | 2 +-
.../batteryCirculatorFanServiceData.html | 2 +-
docs/types/batteryCirculatorFanStatus.html | 2 +-
.../batteryCirculatorFanWebhookContext.html | 2 +-
docs/types/blindTilt.html | 2 +-
docs/types/blindTiltServiceData.html | 2 +-
docs/types/blindTiltStatus.html | 2 +-
docs/types/blindTiltWebhookContext.html | 2 +-
docs/types/bot.html | 2 +-
docs/types/botServiceData.html | 2 +-
docs/types/botStatus.html | 2 +-
docs/types/botWebhookContext.html | 2 +-
docs/types/ceilingLight.html | 2 +-
docs/types/ceilingLightPro.html | 2 +-
docs/types/ceilingLightProServiceData.html | 2 +-
docs/types/ceilingLightProStatus.html | 2 +-
docs/types/ceilingLightProWebhookContext.html | 2 +-
docs/types/ceilingLightServiceData.html | 2 +-
docs/types/ceilingLightStatus.html | 2 +-
docs/types/ceilingLightWebhookContext.html | 2 +-
docs/types/circulatorFanStatus.html | 2 +-
docs/types/circulatorFanWebhookContext.html | 2 +-
docs/types/colorBulb.html | 2 +-
docs/types/colorBulbServiceData.html | 2 +-
docs/types/colorBulbStatus.html | 2 +-
docs/types/colorBulbWebhookContext.html | 2 +-
docs/types/contactSensor.html | 2 +-
docs/types/contactSensorServiceData.html | 2 +-
docs/types/contactSensorStatus.html | 2 +-
docs/types/contactSensorWebhookContext.html | 2 +-
docs/types/curtain.html | 2 +-
docs/types/curtain3.html | 2 +-
docs/types/curtain3ServiceData.html | 2 +-
docs/types/curtain3WebhookContext.html | 2 +-
docs/types/curtainServiceData.html | 2 +-
docs/types/curtainStatus.html | 2 +-
docs/types/curtainWebhookContext.html | 2 +-
docs/types/floorCleaningRobotS10.html | 2 +-
docs/types/floorCleaningRobotS10Status.html | 2 +-
.../floorCleaningRobotS10WebhookContext.html | 2 +-
docs/types/hub2.html | 2 +-
docs/types/hub2ServiceData.html | 2 +-
docs/types/hub2Status.html | 2 +-
docs/types/hub2WebhookContext.html | 2 +-
docs/types/humidifier.html | 2 +-
docs/types/humidifier2ServiceData.html | 2 +-
docs/types/humidifier2Status.html | 2 +-
docs/types/humidifier2WebhookContext.html | 2 +-
docs/types/humidifierServiceData.html | 2 +-
docs/types/humidifierStatus.html | 2 +-
docs/types/humidifierWebhookContext.html | 2 +-
docs/types/indoorCam.html | 2 +-
docs/types/indoorCameraWebhookContext.html | 2 +-
docs/types/keypad.html | 2 +-
docs/types/keypadDetectorServiceData.html | 2 +-
docs/types/keypadTouch.html | 2 +-
docs/types/keypadTouchWebhookContext.html | 2 +-
docs/types/keypadWebhookContext.html | 2 +-
docs/types/lock.html | 2 +-
docs/types/lockPro.html | 2 +-
docs/types/lockProServiceData.html | 2 +-
docs/types/lockProStatus.html | 2 +-
docs/types/lockProWebhookContext.html | 2 +-
docs/types/lockServiceData.html | 2 +-
docs/types/lockStatus.html | 2 +-
docs/types/lockWebhookContext.html | 2 +-
docs/types/meter.html | 2 +-
docs/types/meterPlus.html | 2 +-
docs/types/meterPlusServiceData.html | 2 +-
docs/types/meterPlusStatus.html | 2 +-
docs/types/meterPlusWebhookContext.html | 2 +-
docs/types/meterPro.html | 2 +-
docs/types/meterProCO2ServiceData.html | 2 +-
docs/types/meterProCO2Status.html | 2 +-
docs/types/meterProCO2WebhookContext.html | 2 +-
docs/types/meterProServiceData.html | 2 +-
docs/types/meterProStatus.html | 2 +-
docs/types/meterProWebhookContext.html | 2 +-
docs/types/meterServiceData.html | 2 +-
docs/types/meterStatus.html | 2 +-
docs/types/meterWebhookContext.html | 2 +-
docs/types/motionSensor.html | 2 +-
docs/types/motionSensorServiceData.html | 2 +-
docs/types/motionSensorStatus.html | 2 +-
docs/types/motionSensorWebhookContext.html | 2 +-
docs/types/onadvertisement.html | 2 +-
docs/types/ondiscover.html | 2 +-
docs/types/outdoorMeter.html | 2 +-
docs/types/outdoorMeterServiceData.html | 2 +-
docs/types/outdoorMeterStatus.html | 2 +-
docs/types/outdoorMeterWebhookContext.html | 2 +-
docs/types/panTiltCamWebhookContext.html | 2 +-
docs/types/pantiltCam.html | 2 +-
docs/types/pantiltCam2k.html | 2 +-
docs/types/plug.html | 2 +-
docs/types/plugMini.html | 2 +-
docs/types/plugMiniJPServiceData.html | 2 +-
docs/types/plugMiniJPWebhookContext.html | 2 +-
docs/types/plugMiniStatus.html | 2 +-
docs/types/plugMiniUSServiceData.html | 2 +-
docs/types/plugMiniUSWebhookContext.html | 2 +-
docs/types/plugStatus.html | 2 +-
docs/types/plugWebhookContext.html | 2 +-
docs/types/relaySwitch1Context.html | 2 +-
docs/types/relaySwitch1PMContext.html | 2 +-
docs/types/relaySwitch1PMServiceData.html | 2 +-
docs/types/relaySwitch1PMStatus.html | 2 +-
docs/types/relaySwitch1ServiceData.html | 2 +-
docs/types/relaySwitch1Status.html | 2 +-
docs/types/remote.html | 2 +-
docs/types/remoteServiceData.html | 2 +-
docs/types/robotVacuumCleanerS1.html | 2 +-
docs/types/robotVacuumCleanerS1Plus.html | 2 +-
.../types/robotVacuumCleanerS1PlusStatus.html | 2 +-
...obotVacuumCleanerS1PlusWebhookContext.html | 2 +-
docs/types/robotVacuumCleanerS1Status.html | 2 +-
.../robotVacuumCleanerS1WebhookContext.html | 2 +-
docs/types/robotVacuumCleanerServiceData.html | 2 +-
docs/types/stripLight.html | 2 +-
docs/types/stripLightServiceData.html | 2 +-
docs/types/stripLightStatus.html | 2 +-
docs/types/stripLightWebhookContext.html | 2 +-
docs/types/waterLeakDetector.html | 2 +-
docs/types/waterLeakDetectorServiceData.html | 2 +-
docs/types/waterLeakDetectorStatus.html | 2 +-
.../waterLeakDetectorWebhookContext.html | 2 +-
190 files changed, 798 insertions(+), 633 deletions(-)
create mode 100644 .github/copilot-instructions.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..67e1454c
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,165 @@
+# Node-SwitchBot Development Instructions
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Setup
+- Install Node.js (^20 || ^22 || ^24): Use the existing version if available
+- Install dependencies: `npm install` -- takes ~5-25 seconds (varies by cache). **NEVER CANCEL**
+- Build the project: `npm run build` -- takes ~5 seconds. **NEVER CANCEL**
+- Run tests: `npm run test` -- takes ~1 second with 12 tests. **NEVER CANCEL**
+
+### Development Workflow
+- **ALWAYS run these commands in order when starting work:**
+ 1. `npm install`
+ 2. `npm run build`
+ 3. `npm run test`
+ 4. `npm run lint`
+- **Build and validate EVERY change**: After any code modification, always run `npm run build && npm run test && npm run lint`
+- **NEVER skip linting**: Run `npm run lint` before committing or the CI (.github/workflows/build.yml) will fail
+- **Use lint:fix for automatic fixes**: `npm run lint:fix` to automatically fix ESLint issues
+
+### Platform Requirements and Constraints
+- **BLE functionality requires Linux-based OS only** (Raspbian, Ubuntu, etc.)
+- **Windows and macOS are NOT supported** for BLE operations (use OpenAPI instead)
+- **Node.js versions**: Must use ^20, ^22, or ^24 (currently using v20.19.4)
+- **ES Modules**: This project uses `"type": "module"` - always use ES import/export syntax
+
+### Testing and Validation
+- **Basic functionality test**: After any changes to core classes, run this validation:
+ ```javascript
+ const { SwitchBotBLE, SwitchBotOpenAPI } = require('./dist/index.js');
+ const ble = new SwitchBotBLE(); // Should not throw
+ const api = new SwitchBotOpenAPI('test', 'test'); // Should not throw
+ ```
+- **Complete test suite**: `npm run test` (12 tests) -- should always pass before committing
+- **Test coverage**: `npm run test-coverage` to see coverage report (~15% coverage is normal)
+- **Documentation generation**: `npm run docs` generates TypeDoc documentation in ./docs/
+
+### Build and Timing Expectations
+- **npm install**: ~5-25 seconds (varies by cache) -- **NEVER CANCEL**. Set timeout to 5+ minutes for safety
+- **npm run build**: ~5 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+- **npm run test**: ~1 second (12 tests) -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+- **npm run lint**: ~3 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+- **npm run docs**: ~2 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+
+## Project Structure and Key Files
+
+### Source Code Organization
+- **src/index.ts**: Main export file - exports SwitchBotBLE, SwitchBotOpenAPI, and device classes
+- **src/switchbot-ble.ts**: Bluetooth Low Energy interface for direct device control
+- **src/switchbot-openapi.ts**: HTTP API interface for cloud-based SwitchBot control
+- **src/device.ts**: Individual device classes (WoHand, WoCurtain, WoSmartLock, etc.)
+- **src/types/**: TypeScript type definitions for all device interfaces
+- **src/settings.ts**: Configuration constants and API URLs
+- **dist/**: Compiled JavaScript output (generated by `npm run build`)
+
+### Configuration Files
+- **package.json**: Main project config - scripts, dependencies, ES module config
+- **tsconfig.json**: TypeScript compilation settings (target: ES2022, module: ES2022)
+- **eslint.config.js**: ESLint configuration using @antfu/eslint-config
+- **jest.config.js**: Test configuration (uses Vitest, not Jest)
+- **.gitignore**: Excludes dist/, node_modules/, coverage/, and build artifacts
+
+### Documentation
+- **README.md**: Main project documentation and installation instructions
+- **BLE.md**: Comprehensive BLE usage documentation and device examples
+- **OpenAPI.md**: OpenAPI usage documentation and authentication setup
+- **CHANGELOG.md**: Version history and release notes
+- **docs/**: Generated TypeDoc API documentation (HTML format)
+
+## Common Development Tasks
+
+### Adding New Device Support
+- **Add device class**: Create new class in src/device.ts extending SwitchbotDevice
+- **Update exports**: Add export to src/index.ts
+- **Add type definitions**: Create types in src/types/ if needed
+- **Test basic instantiation**: Ensure the device class can be imported and instantiated
+- **Always run full build and test cycle**: `npm run build && npm run test && npm run lint`
+
+### API Changes and Extensions
+- **OpenAPI changes**: Modify src/switchbot-openapi.ts
+- **BLE changes**: Modify src/switchbot-ble.ts
+- **Update type definitions**: Modify corresponding files in src/types/
+- **Always verify exports**: Check that new functionality is exported in src/index.ts
+- **Test import functionality**: Verify new exports can be imported correctly
+
+### Working with Dependencies
+- **Noble (BLE)**: @stoprocent/noble for Bluetooth functionality - Linux only
+- **HTTP requests**: Uses undici for HTTP calls (not axios or fetch)
+- **Async operations**: Uses async-mutex for concurrency control
+- **Adding dependencies**: Use `npm install --save` for runtime deps, `--save-dev` for dev deps
+
+## Validation and Quality Assurance
+
+### Pre-commit Checklist
+1. **Build succeeds**: `npm run build` completes without errors
+2. **All tests pass**: `npm run test` shows all 12 tests passing
+3. **Linting passes**: `npm run lint` shows no errors
+4. **Documentation builds**: `npm run docs` generates without warnings
+5. **Basic import works**: Can import and instantiate main classes
+
+### Manual Testing Scenarios
+- **SwitchBotBLE instantiation**: `new SwitchBotBLE()` should not throw errors
+- **SwitchBotOpenAPI instantiation**: `new SwitchBotOpenAPI('token', 'secret')` should not throw
+- **Module exports**: All exported classes should be importable from main package
+- **TypeScript compilation**: No TypeScript errors in dist/ output
+- **Documentation completeness**: Check that new public APIs appear in generated docs
+
+### CI/CD Integration
+- **GitHub Actions**: Build runs on push to 'latest' branch and PRs
+- **External workflows**: Uses OpenWonderLabs/.github/.github/workflows/nodejs-build-and-test.yml
+- **Required checks**: Build, test, and lint must all pass
+- **Coverage reporting**: Test coverage is tracked and reported
+
+## Troubleshooting Common Issues
+
+### BLE Not Working
+- **Check OS**: BLE only works on Linux-based systems
+- **Install noble prerequisites**: May need additional system libraries for @stoprocent/noble
+- **Use OpenAPI instead**: For Windows/macOS development, use SwitchBotOpenAPI class
+
+### Build Failures
+- **Check Node.js version**: Must be ^20, ^22, or ^24
+- **Clean and rebuild**: `npm run clean && npm install && npm run build`
+- **TypeScript errors**: Check tsconfig.json settings and type definitions
+
+### Test Failures
+- **Run individual tests**: Use `npm run test:watch` for interactive testing
+- **Check imports**: Ensure all imports use correct ES module syntax
+- **Verify exports**: Check that src/index.ts exports all necessary components
+
+### Linting Errors
+- **Auto-fix**: Use `npm run lint:fix` to automatically fix many issues
+- **ESLint config**: Review eslint.config.js for current rules
+- **Import sorting**: ESLint enforces specific import order - use lint:fix
+
+## Frequently Referenced Information
+
+### Package Scripts (from package.json)
+```bash
+npm run build # Clean and compile TypeScript
+npm run test # Run test suite with Vitest
+npm run lint # Run ESLint on src/**/*.ts
+npm run lint:fix # Auto-fix ESLint issues
+npm run docs # Generate TypeDoc documentation
+npm run clean # Remove dist/ directory
+npm run watch # Build and link for development
+```
+
+### Main Exports (from src/index.ts)
+- **SwitchBotBLE**: Bluetooth interface class
+- **SwitchBotOpenAPI**: HTTP API interface class
+- **SwitchbotDevice**: Base device class
+- **Device classes**: WoHand, WoCurtain, WoSmartLock, etc.
+- **Type definitions**: All device status and response types
+
+### Dependencies Summary
+- **@stoprocent/noble**: BLE functionality (Linux only)
+- **undici**: HTTP client for API requests
+- **async-mutex**: Concurrency control
+- **TypeScript**: Language and compilation
+- **Vitest**: Testing framework
+- **ESLint**: Code linting with @antfu/eslint-config
+- **TypeDoc**: API documentation generation
\ No newline at end of file
diff --git a/docs/classes/Advertising.html b/docs/classes/Advertising.html
index 8e7c0ec6..b028ea19 100644
--- a/docs/classes/Advertising.html
+++ b/docs/classes/Advertising.html
@@ -1,8 +1,8 @@
Advertising | node-switchbot Staticparse parse ( Â Â Â Â
peripheral : Peripheral , Â Â Â Â
emitLog : ( level : string , message : string ) => void , ) : Promise < null | ad >
Staticparse parse ( Â Â Â Â
peripheral : Peripheral , Â Â Â Â
emitLog : ( level : string , message : string ) => void , ) : Promise < null | ad > Returns Promise < null | ad >
An object containing parsed data specific to the SwitchBot device type, or null if the device is not recognized.
-
Staticparse parseServiceData ( Â Â Â Â
model : string , Â Â Â Â
serviceData : Buffer , Â Â Â Â
manufacturerData : Buffer , Â Â Â Â
emitLog : ( level : string , message : string ) => void , ) : Promise < any > Staticparse parseServiceData ( Â Â Â Â
model : string , Â Â Â Â
serviceData : Buffer , Â Â Â Â
manufacturerData : Buffer , Â Â Â Â
emitLog : ( level : string , message : string ) => void , ) : Promise < any > Parameters model : string serviceData : Buffer manufacturerData : Buffer Returns Promise < any >
-
+
Represents the advertising data parser for SwitchBot devices.
-