# CLAUDE.md

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

## Overview

This is a Synology DSM API client library and CLI tool. It provides a Python interface to interact with Synology NAS via the WebAPI, supporting login, session reuse, and system information retrieval.

## Architecture

### Core Components

- **`scripts/synology_api.py`** - The `DSMApiClient` library class. Handles authentication, session management, and API calls. Uses only stdlib (urllib, ssl, json).

- **`scripts/synology_api_login.py`** - CLI wrapper that uses the library. Supports profile-based configuration, SID session caching, and system info retrieval with human-readable or JSON output.

### Session Management

The client caches SID sessions to avoid repeated logins:
1. On run, checks `tmp/synology_session.json` for a valid SID
2. If SID is still valid (probed via `get_system_info`), reuses it
3. Otherwise, performs full login and saves new session

### Configuration Methods

Two ways to configure credentials:

1. **Environment variables** (`.env` in workspace root):
   ```
   DS_URL=https://syno.example.com/
   DS_USER=username
   DS_PASSWORD=password
   ```

2. **Profiles** (`references/hosts.json`):
   ```json
   {
     "profile-name": {
       "url": "https://nas.local:5001",
       "user": "username",
       "password_env": "DS_PASSWORD_PROFILE"
     }
   }
   ```
   Use with `--profile profile-name`

## Common Commands

### Basic login (with session caching)
```bash
python3 scripts/synology_api_login.py
```

### Get system info with human-readable summary
```bash
python3 scripts/synology/api_login.py --system-info --summary
```

### Get system info as compact JSON (for scripting)
```bash
python3 scripts/synology_api_login.py --system-info --json-compact
```

### Using a profile from hosts.json
```bash
python3 scripts/synology_api_login.py --profile home-nas --system-info --summary
```

### Direct credentials (overrides env vars)
```bash
python3 scripts/synology_api_login.py --url "https://192.168.1.10:5001" --user admin --password "xxx" --system-info
```

## Output Files

- `tmp/synology_api_login_result.json` - Login result metadata
- `tmp/synology_session.json` - Cached SID session
- `tmp/synology_system_info.json` - Full API responses bundle

## API Fallback Pattern

DSM versions vary in API support. The client uses `_try_api_candidates()` which tries multiple endpoint/version combinations and returns the first successful response. When adding new API methods, follow this pattern for compatibility.

## Compact JSON Schema

The `--json-compact` output normalizes across DSM versions and includes:
- `model`, `serial`, `ip` (prefers eth0)
- `dsm_version`, `cpu_usage_pct`, `cpu_clock_mhz`
- `memory_total_mb`, `memory_usage_pct`, `temperature_c`
- `volumes` (list), `disk_size_usage` (bytes + GiB), `disk_health`
- `time`, `uptime`