feat: initial release

Author: linchengyu

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+        continue-on-error: true
+
+      - name: Check dist exists
+        run: |
+          if [ ! -d "dist" ]; then
+            echo "Error: dist directory not found after build"
+            exit 1
+          fi
+          echo "✅ Build output verified"
+
+      - name: Verify package files
+        run: |
+          if [ ! -f "dist/index.js" ]; then
+            echo "Error: dist/index.js not found"
+            exit 1
+          fi
+          if [ ! -f "dist/index.d.ts" ]; then
+            echo "Error: dist/index.d.ts not found"
+            exit 1
+          fi
+          echo "✅ Package files verified"

.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Publish to npm (on tag)
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+        continue-on-error: true
+
+      - name: Verify package.json version matches tag
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "Error: Tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+          echo "Version check passed: $TAG_VERSION"
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          draft: false
+          prerelease: false

.gitignore

@@ -0,0 +1,68 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Production builds
+dist/
+build/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test coverage
+coverage/
+*.lcov
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# TypeScript
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# Jest coverage
+coverage/
+
+# ESLint cache
+.eslintcache
+
+# Temporary folders
+tmp/
+temp/

README.md

@@ -0,0 +1,182 @@
+# SwitchBot Channel for OpenClaw
+
+> Connect your SwitchBot smart home devices to OpenClaw platform for real-time device status monitoring
+
+## 📖 Project Overview
+
+SwitchBot Channel is an official channel plugin for the OpenClaw platform that receives real-time SwitchBot device status changes via MQTT protocol. Whether it's contact sensors, temperature/humidity meters, or smart plugs, you can monitor device status in real-time through OpenClaw and set up intelligent notifications.
+
+## ✨ Features
+
+- 🔄 **Real-time Sync**: Receive device status via MQTT in real-time
+- 🏠 **Device Compatibility**: Support for all mainstream SwitchBot devices
+- 🔑 **Auto Authentication**: Intelligent credential management with auto-renewal
+- 🚨 **Smart Notifications**: Send notifications only for important events to avoid interruptions
+- 🔧 **Zero Configuration**: Out-of-the-box functionality with just SwitchBot Token and Secret
+- 📊 **History Records**: Local storage of device status history
+- 🛡️ **High Availability**: Auto-reconnection with automatic recovery after network interruptions
+
+## 🚀 Quick Start
+
+### System Requirements
+
+- **OpenClaw**: >= 2026.1.0
+- **Node.js**: >= 18.0.0
+- **SwitchBot App**: Latest version
+
+### Step 1: Install Plugin
+
+#### Prerequisites
+
+Before installing the plugin, ensure your OpenClaw environment has the required dependencies:
+
+```bash
+# Install pnpm if not already installed
+npm install -g pnpm
+
+# Install dependencies in your OpenClaw installation
+pnpm install
+```
+
+#### Installation
+
+```bash
+# Install plugin from npm
+openclaw plugins install @switchbot/openclaw-channel-switchbot
+
+# Verify installation
+openclaw plugins list
+```
+
+### Step 2: Get SwitchBot Credentials
+
+1. **Open SwitchBot App**
+2. **Enter Developer Options**:
+   - Tap "Settings" in bottom right
+   - Find and tap "Developer Options"
+   - If this option doesn't exist, ensure the App is updated to the latest version
+
+3. **Get Credentials**:
+   - Record the **Token** (64-character string)
+   - Record the **Secret** (32-character string)
+
+> ⚠️ **Important**: Keep your Token and Secret secure and don't share them with others
+
+### Step 3: Configure OpenClaw
+
+Edit OpenClaw configuration file `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-channel-switchbot": {
+        "enabled": true
+      }
+    }
+  },
+  "channels": {
+    "switchbot": {
+      "enabled": true,
+      "token": "your_switchbot_token_here",
+      "secret": "your_switchbot_secret_here"
+    }
+  }
+}
+```
+
+### Step 4: Start Service
+
+```bash
+# Restart OpenClaw Gateway
+openclaw gateway restart
+
+# Check plugin status
+openclaw status
+```
+
+## ⚙️ Configuration Details
+
+### Basic Configuration
+
+```json
+{
+  "channels": {
+    "switchbot": {
+      "enabled": true,
+      "token": "xxxx",
+      "secret": "xxxx"
+    }
+  }
+}
+```
+
+## 📱 Usage Guide
+
+### Device Status Monitoring
+
+After the plugin starts, it will automatically receive status changes from all devices. You can view them using:
+
+```bash
+# View device status
+openclaw devices list switchbot
+
+# View specific device
+openclaw devices show <device_id>
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+#### Q: Plugin fails to start
+**A**: Check configuration
+
+```bash
+# Check configuration syntax
+openclaw config validate
+
+# View detailed errors
+openclaw gateway logs --follow
+```
+
+### Debug Mode
+
+Enable detailed logging for troubleshooting:
+
+```json
+{
+  "logging": {
+    "level": "debug",
+    "channels": {
+      "switchbot": "debug"
+    }
+  }
+}
+```
+
+View logs:
+```bash
+# View real-time logs
+tail -f ~/.openclaw/logs/gateway.log | grep "SwitchBot"
+
+# View error logs
+openclaw gateway logs --level error
+```
+
+### Reset Plugin
+
+If you encounter serious issues, you can reset the plugin:
+
+```bash
+# Stop service
+openclaw gateway stop
+
+# Clear plugin cache
+rm -rf ~/.openclaw/cache/plugins/switchbot
+
+# Restart
+openclaw gateway start
+```
+
+**Made with ❤️ by the SwitchBot Team**