107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# 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/Hostex reservations, automatically creating and managing visitor access for Airbnb guests. The system fetches reservations from either Hostex API or Airbnb ICS feed, creates UniFi Access visitor accounts with PIN codes based on phone numbers, and provides cross-verification between multiple booking systems.
|
|
|
|
## 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`
|
|
|
|
### 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)
|
|
|
|
## 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 |