eufy-security-client-dz/CLAUDE.md

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

npm run build          # Full build (compiles TypeScript)
npm run build:ts       # TypeScript compilation + copy proto files

Development

npm run watch          # Watch mode (auto-recompile on changes)
npm run watch:ts       # Watch TypeScript files only

Linting

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