# 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