131 lines
5.1 KiB
Markdown
131 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
This is a TypeScript client library for controlling Eufy Security devices by connecting to Eufy cloud servers and local/remote stations over P2P. The library is published to npm as `eufy-security-client`.
|
|
|
|
**Important:** This project is NOT affiliated with Anker/Eufy Security. It is a personal project maintained in spare time.
|
|
|
|
## Development Commands
|
|
|
|
### Build
|
|
```bash
|
|
npm run build # Full build (compiles TypeScript)
|
|
npm run build:ts # TypeScript compilation + copy proto files
|
|
```
|
|
|
|
### Development
|
|
```bash
|
|
npm run watch # Watch mode (auto-recompile on changes)
|
|
npm run watch:ts # Watch TypeScript files only
|
|
```
|
|
|
|
### Linting
|
|
```bash
|
|
npm run lint # Run ESLint on TypeScript source files
|
|
```
|
|
|
|
### Testing
|
|
Currently, there are no tests configured (`npm test` exits with error).
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
The library is organized into four major subsystems, each with its own directory:
|
|
|
|
1. **HTTP API (`src/http/`)** - Eufy Cloud API communication
|
|
- `api.ts`: Main HTTPApi class handling authentication and cloud requests
|
|
- `device.ts`: Device class hierarchy (Camera, Lock, Doorbell, Sensor types, etc.)
|
|
- `station.ts`: Station/Hub management
|
|
- Uses encrypted API v2 communication with RSA/ECDH key exchange
|
|
- Handles authentication including 2FA and captcha
|
|
|
|
2. **P2P Communication (`src/p2p/`)** - Direct peer-to-peer connection with stations/devices
|
|
- `session.ts`: P2PClientProtocol handles UDP-based P2P protocol
|
|
- Supports local and remote connectivity to stations
|
|
- Handles livestreaming, video download, commands (lock/unlock, enable/disable, etc.)
|
|
- Complex packet sequencing and encryption handling
|
|
- Supports multiple encryption types (none, type1, type2)
|
|
|
|
3. **Push Notifications (`src/push/`)** - Unified push message interface
|
|
- `service.ts`: PushNotificationService manages FCM-based notifications
|
|
- `parser.ts`: Normalizes different push notification types
|
|
- Handles motion, person detection, doorbell ring events, etc.
|
|
|
|
4. **MQTT (`src/mqtt/`)** - MQTT subscription for certain devices
|
|
- Supports Smart Lock Touch & Wifi and similar MQTT-enabled devices
|
|
|
|
### Main Entry Point
|
|
|
|
- **`src/eufysecurity.ts`**: The `EufySecurity` class is the high-level orchestrator
|
|
- Must be initialized with `EufySecurity.initialize()` (async factory pattern)
|
|
- Manages all stations, devices, and houses
|
|
- Coordinates HTTP API, P2P connections, push notifications, and MQTT
|
|
- Emits typed events for device/station state changes
|
|
- Handles persistent data storage for credentials and state
|
|
|
|
### Key Design Patterns
|
|
|
|
- **Typed Event Emitters**: Uses `tiny-typed-emitter` throughout for type-safe events
|
|
- **Async Initialization**: Main classes use static `initialize()` factory methods instead of constructors
|
|
- **Persistent Data**: Credentials and session data saved to filesystem (default: `.eufy-security-client/`)
|
|
- **Property System**: Devices/stations have a metadata-driven property system with read-only/write restrictions
|
|
- **Command Queue**: P2P commands are queued and executed sequentially per station
|
|
|
|
### Communication Layers
|
|
|
|
```
|
|
EufySecurity (High-level API)
|
|
├── HTTPApi (Cloud API for device metadata, authentication)
|
|
├── P2PClientProtocol (Direct station communication for commands/streaming)
|
|
├── PushNotificationService (Real-time event notifications)
|
|
└── MQTTService (MQTT-enabled device events)
|
|
```
|
|
|
|
### Device Hierarchy
|
|
|
|
All devices inherit from base `Device` class with specialized subclasses:
|
|
- Camera types: `Camera`, `IndoorCamera`, `SoloCamera`, `FloodlightCamera`, `WallLightCam`, `GarageCamera`
|
|
- Doorbell types: `BatteryDoorbellCamera`, `WiredDoorbellCamera`, `DoorbellLock`
|
|
- Lock types: `Lock`, `LockKeypad`
|
|
- Sensors: `EntrySensor`, `MotionSensor`
|
|
- Other: `Keypad`, `SmartSafe`, `SmartDrop`, `Tracker`
|
|
|
|
Each device type has specific properties and commands based on hardware capabilities.
|
|
|
|
## TypeScript Configuration
|
|
|
|
- Target: ES2022
|
|
- Module: Node16 with Node16 resolution
|
|
- Strict mode enabled
|
|
- Build output: `build/` directory
|
|
- Source maps generated
|
|
- Declaration files (`.d.ts`) generated for npm package
|
|
|
|
## Publishing
|
|
|
|
- Main entry: `build/index.js`
|
|
- Requires Node.js >= 20.0.0
|
|
- Uses `prepublishOnly` script to ensure build runs before publishing
|
|
- Proto files (`.proto`) and certificates (`.crt`) are copied to build directory
|
|
|
|
## P2P Protocol Notes
|
|
|
|
The P2P protocol is UDP-based with custom sequencing and encryption:
|
|
- Supports local (LAN) and remote (through Eufy cloud) connections
|
|
- Uses magic word `0xf1e2d3c4` in packet headers
|
|
- Multiple encryption modes with AES and RSA
|
|
- Handles livestreaming with separate video/audio packet sequencing
|
|
- Energy-saving devices have different keepalive/timeout strategies
|
|
- Smart locks use BLE-style command structures wrapped in P2P
|
|
|
|
## Logging
|
|
|
|
Uses `typescript-logging` with category-based logging:
|
|
- Categories: HTTP, P2P, PUSH, MQTT
|
|
- Configurable log levels per category
|
|
- Default logger can be replaced via `EufySecurity.initialize()` config
|