unifi-access-airbnb/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Python automation tool that integrates UniFi Access with Airbnb reservations, automatically creating and managing visitor access for Airbnb guests. The system fetches reservations from Airbnb ICS calendar feed, creates UniFi Access visitor accounts with PIN codes based on phone numbers, and provides comprehensive logging and monitoring.

## Current Production Configuration

### UniFi Access Settings
- **Controller IP**: `10.0.1.20:12445`
- **API Token**: `bNILUGf8zWZE6PVv926xAA` (Access API key with full visitor management permissions)
- **Target Door Device**: `847848a02017` (configured for individual door access, not door groups)

### Airbnb Integration
- **ICS Calendar URL**: `https://www.airbnb.com/calendar/ical/1554481759780111413.ics?s=19f2a0faa64e47fd28a9879954c9a5c2`
- **Check-in Time**: `16:00:00` (4:00 PM)
- **Check-out Time**: `11:00:00` (11:00 AM)
- **PIN Code Digits**: `4` (uses last 4 digits of guest phone number)

### Repository Setup
- **Primary Repository**: `https://git.cybertek.systems/cnicholas/unifi-access-airbnb.git`
- **Original Source**: `https://github.com/keithah/unifi-access-airbnb.git` (upstream reference)

## Core Commands

### Development and Execution
- **Run the application**: `python3 main.py`
- **Install dependencies**: `pip install -r requirements.txt`
- **Run with verbose logging**: `python3 main.py -v`
- **Specify custom log file**: `python3 main.py -l custom.log`
- **List available door groups**: `python3 main.py --list-door-groups`

### Docker Deployment (Recommended)
- **Build and run continuously**: `docker-compose up -d`
- **Run once manually**: `docker-compose --profile manual up unifi-access-airbnb-once`
- **View logs**: `docker-compose logs -f`
- **Stop container**: `docker-compose down`

### Configuration Setup
- **Setup configuration**: `cp unifi.conf.example unifi.conf` then edit with actual credentials
- **Configuration file**: `unifi.conf` (contains API tokens, URLs, and settings)
- **Logs directory**: `logs/` (persistent storage for container deployments)

## Architecture Overview

### Core Components

1. **main.py** - Entry point and orchestration
   - Handles command-line arguments and logging setup
   - Coordinates all managers and performs cross-system verification
   - Implements `verify_across_systems()` for data consistency checks

2. **unifi_access.py** - UniFi Access API integration
   - `UnifiAccessManager` class handles all UniFi Access operations
   - Creates/deletes visitors, assigns PIN codes, manages door group access
   - Processes reservations and maintains visitor lifecycle

3. **hostex_api.py** - Hostex API integration
   - `HostexManager` fetches reservations from Hostex booking platform
   - Simple API wrapper for reservation data

4. **ics_parser.py** - Airbnb ICS calendar parsing
   - `ICSParser` processes Airbnb calendar feeds
   - Extracts reservation data and PIN codes from ICS events

5. **notification.py** - Simplepush notifications
   - `NotificationManager` sends status updates and alerts
   - Configurable notification system for operational updates

6. **config.py** - Configuration management
   - Centralizes configuration loading from `unifi.conf`
   - Handles API credentials, timing settings, and feature flags

7. **utils.py** - Shared utilities
   - Logging setup and configuration

### Data Flow Architecture

```
Hostex API ──┐
             ├──► Cross-Verification ──► UniFi Access API
ICS Feed ────┘                          (Visitor Management)
                                              │
                                              ▼
                                        Simplepush Notifications
```

### Key Integration Points

- **Reservation Sources**: Supports both Hostex API and Airbnb ICS feeds
- **PIN Code Generation**: Uses last N digits of guest phone numbers
- **Cross-Verification**: Matches reservations across systems to detect discrepancies
- **Visitor Lifecycle**: Automatically creates visitors for upcoming stays, deletes past/completed visits
- **Door Access**: Assigns visitors to configurable door groups in UniFi Access

## Configuration Structure

The `unifi.conf` file contains these key sections:
- `[UniFi]`: Access controller API endpoint and authentication token
- `[Hostex]`: Hostex API credentials (optional if using ICS only)
- `[Airbnb]`: ICS calendar feed URL (optional if using Hostex only)
- `[Door]`: Default door group ID for visitor access
- `[Visitor]`: Check-in/out times and PIN code settings
- `[Simplepush]`: Notification service configuration
- `[General]`: Logging and PIN code digit count

## Development Notes

### Dependencies
- `requests`: HTTP API calls to UniFi Access and Hostex
- `icalendar`: Parsing Airbnb ICS calendar feeds
- `urllib3`: HTTP utilities (with SSL warning suppression)
- `configparser`: Configuration file parsing

### Logging Strategy
- Comprehensive debug logging available with `-v` flag
- File-based logging for operational history
- Different log levels for console vs file output

### API Integrations
- **UniFi Access**: RESTful API for visitor management, requires authentication token
- **Hostex**: Booking platform API for reservation data
- **Simplepush**: Simple HTTP-based notification service
- **Airbnb ICS**: Calendar feed parsing for reservation extraction

### Testing and Verification
- Use `--list-door-groups` to verify UniFi Access connectivity and available door groups
- Run with `-v` flag to see detailed operation logs
- Check log files for historical operation data and error analysis

## Project Status and Setup History

### Successfully Completed Setup
- ✅ UniFi Access API connection verified (10.0.1.20:12445)
- ✅ API token configured with proper Access permissions (not Console permissions)
- ✅ Individual door device configuration implemented (847848a02017)
- ✅ Airbnb ICS calendar integration working
- ✅ Docker containerization completed with multi-architecture support
- ✅ Raspberry Pi compatibility verified
- ✅ Repository migrated to git.cybertek.systems

### Key Implementation Notes
- **Door Groups vs Individual Doors**: This implementation uses individual door devices (`"type": "door"`) rather than door groups (`"type": "door_group"`) due to UniFi Access UI configuration
- **API Token Type**: Must use UniFi Access API token (not Console API token) for visitor management permissions
- **Multi-day Stays**: System creates single visitor account spanning entire stay duration (check-in to check-out)
- **PIN Code Strategy**: Uses last 4 digits of guest phone number from Airbnb booking data

### Testing Status
- **Ready for hardware testing**: Awaiting UniFi reader installation
- **Configuration validated**: All API connections and calendar parsing working
- **Docker deployment tested**: Container builds and runs successfully

### Future Development
- **UniFi Protect Integration**: Planned expansion for automated recording based on guest stays
- **Required Hardware**: UniFi Gateway Max or Cloud Key Gen2+ with Protect license
- **Features**: Guest check-in/out recording, incident documentation, privacy controls

## Troubleshooting Common Issues

### API Connection Problems
- Verify controller IP address and port (12445 for UniFi Access)
- Ensure API token is from UniFi Access settings (not Console)
- Check network connectivity to UniFi controller

### Door Group/Device Issues  
- Use individual door device IDs instead of door groups for this implementation
- Verify device ID in UniFi Access dashboard
- Check that device has proper permissions configured

### Calendar Integration Issues
- Verify Airbnb ICS URL is current and accessible
- Check that calendar contains guest phone numbers for PIN generation
- Monitor verbose logs for parsing errors