|
| 1 | +# Node-SwitchBot Development Instructions |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Working Effectively |
| 6 | + |
| 7 | +### Bootstrap and Setup |
| 8 | +- Install Node.js (^20 || ^22 || ^24): Use the existing version if available |
| 9 | +- Install dependencies: `npm install` -- takes ~5-25 seconds (varies by cache). **NEVER CANCEL** |
| 10 | +- Build the project: `npm run build` -- takes ~5 seconds. **NEVER CANCEL** |
| 11 | +- Run tests: `npm run test` -- takes ~1 second with 12 tests. **NEVER CANCEL** |
| 12 | + |
| 13 | +### Development Workflow |
| 14 | +- **ALWAYS run these commands in order when starting work:** |
| 15 | + 1. `npm install` |
| 16 | + 2. `npm run build` |
| 17 | + 3. `npm run test` |
| 18 | + 4. `npm run lint` |
| 19 | +- **Build and validate EVERY change**: After any code modification, always run `npm run build && npm run test && npm run lint` |
| 20 | +- **NEVER skip linting**: Run `npm run lint` before committing or the CI (.github/workflows/build.yml) will fail |
| 21 | +- **Use lint:fix for automatic fixes**: `npm run lint:fix` to automatically fix ESLint issues |
| 22 | + |
| 23 | +### Platform Requirements and Constraints |
| 24 | +- **BLE functionality requires Linux-based OS only** (Raspbian, Ubuntu, etc.) |
| 25 | +- **Windows and macOS are NOT supported** for BLE operations (use OpenAPI instead) |
| 26 | +- **Node.js versions**: Must use ^20, ^22, or ^24 (currently using v20.19.4) |
| 27 | +- **ES Modules**: This project uses `"type": "module"` - always use ES import/export syntax |
| 28 | + |
| 29 | +### Testing and Validation |
| 30 | +- **Basic functionality test**: After any changes to core classes, run this validation: |
| 31 | + ```javascript |
| 32 | + const { SwitchBotBLE, SwitchBotOpenAPI } = require('./dist/index.js'); |
| 33 | + const ble = new SwitchBotBLE(); // Should not throw |
| 34 | + const api = new SwitchBotOpenAPI('test', 'test'); // Should not throw |
| 35 | + ``` |
| 36 | +- **Complete test suite**: `npm run test` (12 tests) -- should always pass before committing |
| 37 | +- **Test coverage**: `npm run test-coverage` to see coverage report (~15% coverage is normal) |
| 38 | +- **Documentation generation**: `npm run docs` generates TypeDoc documentation in ./docs/ |
| 39 | + |
| 40 | +### Build and Timing Expectations |
| 41 | +- **npm install**: ~5-25 seconds (varies by cache) -- **NEVER CANCEL**. Set timeout to 5+ minutes for safety |
| 42 | +- **npm run build**: ~5 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety |
| 43 | +- **npm run test**: ~1 second (12 tests) -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety |
| 44 | +- **npm run lint**: ~3 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety |
| 45 | +- **npm run docs**: ~2 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety |
| 46 | + |
| 47 | +## Project Structure and Key Files |
| 48 | + |
| 49 | +### Source Code Organization |
| 50 | +- **src/index.ts**: Main export file - exports SwitchBotBLE, SwitchBotOpenAPI, and device classes |
| 51 | +- **src/switchbot-ble.ts**: Bluetooth Low Energy interface for direct device control |
| 52 | +- **src/switchbot-openapi.ts**: HTTP API interface for cloud-based SwitchBot control |
| 53 | +- **src/device.ts**: Individual device classes (WoHand, WoCurtain, WoSmartLock, etc.) |
| 54 | +- **src/types/**: TypeScript type definitions for all device interfaces |
| 55 | +- **src/settings.ts**: Configuration constants and API URLs |
| 56 | +- **dist/**: Compiled JavaScript output (generated by `npm run build`) |
| 57 | + |
| 58 | +### Configuration Files |
| 59 | +- **package.json**: Main project config - scripts, dependencies, ES module config |
| 60 | +- **tsconfig.json**: TypeScript compilation settings (target: ES2022, module: ES2022) |
| 61 | +- **eslint.config.js**: ESLint configuration using @antfu/eslint-config |
| 62 | +- **jest.config.js**: Test configuration (uses Vitest, not Jest) |
| 63 | +- **.gitignore**: Excludes dist/, node_modules/, coverage/, and build artifacts |
| 64 | + |
| 65 | +### Documentation |
| 66 | +- **README.md**: Main project documentation and installation instructions |
| 67 | +- **BLE.md**: Comprehensive BLE usage documentation and device examples |
| 68 | +- **OpenAPI.md**: OpenAPI usage documentation and authentication setup |
| 69 | +- **CHANGELOG.md**: Version history and release notes |
| 70 | +- **docs/**: Generated TypeDoc API documentation (HTML format) |
| 71 | + |
| 72 | +## Common Development Tasks |
| 73 | + |
| 74 | +### Adding New Device Support |
| 75 | +- **Add device class**: Create new class in src/device.ts extending SwitchbotDevice |
| 76 | +- **Update exports**: Add export to src/index.ts |
| 77 | +- **Add type definitions**: Create types in src/types/ if needed |
| 78 | +- **Test basic instantiation**: Ensure the device class can be imported and instantiated |
| 79 | +- **Always run full build and test cycle**: `npm run build && npm run test && npm run lint` |
| 80 | + |
| 81 | +### API Changes and Extensions |
| 82 | +- **OpenAPI changes**: Modify src/switchbot-openapi.ts |
| 83 | +- **BLE changes**: Modify src/switchbot-ble.ts |
| 84 | +- **Update type definitions**: Modify corresponding files in src/types/ |
| 85 | +- **Always verify exports**: Check that new functionality is exported in src/index.ts |
| 86 | +- **Test import functionality**: Verify new exports can be imported correctly |
| 87 | + |
| 88 | +### Working with Dependencies |
| 89 | +- **Noble (BLE)**: @stoprocent/noble for Bluetooth functionality - Linux only |
| 90 | +- **HTTP requests**: Uses undici for HTTP calls (not axios or fetch) |
| 91 | +- **Async operations**: Uses async-mutex for concurrency control |
| 92 | +- **Adding dependencies**: Use `npm install --save` for runtime deps, `--save-dev` for dev deps |
| 93 | + |
| 94 | +## Validation and Quality Assurance |
| 95 | + |
| 96 | +### Pre-commit Checklist |
| 97 | +1. **Build succeeds**: `npm run build` completes without errors |
| 98 | +2. **All tests pass**: `npm run test` shows all 12 tests passing |
| 99 | +3. **Linting passes**: `npm run lint` shows no errors |
| 100 | +4. **Documentation builds**: `npm run docs` generates without warnings |
| 101 | +5. **Basic import works**: Can import and instantiate main classes |
| 102 | + |
| 103 | +### Manual Testing Scenarios |
| 104 | +- **SwitchBotBLE instantiation**: `new SwitchBotBLE()` should not throw errors |
| 105 | +- **SwitchBotOpenAPI instantiation**: `new SwitchBotOpenAPI('token', 'secret')` should not throw |
| 106 | +- **Module exports**: All exported classes should be importable from main package |
| 107 | +- **TypeScript compilation**: No TypeScript errors in dist/ output |
| 108 | +- **Documentation completeness**: Check that new public APIs appear in generated docs |
| 109 | + |
| 110 | +### CI/CD Integration |
| 111 | +- **GitHub Actions**: Build runs on push to 'latest' branch and PRs |
| 112 | +- **External workflows**: Uses OpenWonderLabs/.github/.github/workflows/nodejs-build-and-test.yml |
| 113 | +- **Required checks**: Build, test, and lint must all pass |
| 114 | +- **Coverage reporting**: Test coverage is tracked and reported |
| 115 | + |
| 116 | +## Troubleshooting Common Issues |
| 117 | + |
| 118 | +### BLE Not Working |
| 119 | +- **Check OS**: BLE only works on Linux-based systems |
| 120 | +- **Install noble prerequisites**: May need additional system libraries for @stoprocent/noble |
| 121 | +- **Use OpenAPI instead**: For Windows/macOS development, use SwitchBotOpenAPI class |
| 122 | + |
| 123 | +### Build Failures |
| 124 | +- **Check Node.js version**: Must be ^20, ^22, or ^24 |
| 125 | +- **Clean and rebuild**: `npm run clean && npm install && npm run build` |
| 126 | +- **TypeScript errors**: Check tsconfig.json settings and type definitions |
| 127 | + |
| 128 | +### Test Failures |
| 129 | +- **Run individual tests**: Use `npm run test:watch` for interactive testing |
| 130 | +- **Check imports**: Ensure all imports use correct ES module syntax |
| 131 | +- **Verify exports**: Check that src/index.ts exports all necessary components |
| 132 | + |
| 133 | +### Linting Errors |
| 134 | +- **Auto-fix**: Use `npm run lint:fix` to automatically fix many issues |
| 135 | +- **ESLint config**: Review eslint.config.js for current rules |
| 136 | +- **Import sorting**: ESLint enforces specific import order - use lint:fix |
| 137 | + |
| 138 | +## Frequently Referenced Information |
| 139 | + |
| 140 | +### Package Scripts (from package.json) |
| 141 | +```bash |
| 142 | +npm run build # Clean and compile TypeScript |
| 143 | +npm run test # Run test suite with Vitest |
| 144 | +npm run lint # Run ESLint on src/**/*.ts |
| 145 | +npm run lint:fix # Auto-fix ESLint issues |
| 146 | +npm run docs # Generate TypeDoc documentation |
| 147 | +npm run clean # Remove dist/ directory |
| 148 | +npm run watch # Build and link for development |
| 149 | +``` |
| 150 | + |
| 151 | +### Main Exports (from src/index.ts) |
| 152 | +- **SwitchBotBLE**: Bluetooth interface class |
| 153 | +- **SwitchBotOpenAPI**: HTTP API interface class |
| 154 | +- **SwitchbotDevice**: Base device class |
| 155 | +- **Device classes**: WoHand, WoCurtain, WoSmartLock, etc. |
| 156 | +- **Type definitions**: All device status and response types |
| 157 | + |
| 158 | +### Dependencies Summary |
| 159 | +- **@stoprocent/noble**: BLE functionality (Linux only) |
| 160 | +- **undici**: HTTP client for API requests |
| 161 | +- **async-mutex**: Concurrency control |
| 162 | +- **TypeScript**: Language and compilation |
| 163 | +- **Vitest**: Testing framework |
| 164 | +- **ESLint**: Code linting with @antfu/eslint-config |
| 165 | +- **TypeDoc**: API documentation generation |
0 commit comments