# Manitas API

API HTTP para control total de una Mac. Diseñada para que **cualquier IA o script** pueda ver la pantalla y controlar mouse/teclado.

Base URL: `http://<ip-tailscale>:18080` (o `http://127.0.0.1:18080` desde la propia Mac)

Todas las respuestas son JSON salvo `/shot`, que regresa `image/jpeg`.

---

## Ver

### `GET /shot?w=960&display=1`
Captura la pantalla. Regresa JPEG.
- `w`: ancho en px para redimensionar (opcional). Recomendado: `960` (rápido de transferir y suficiente para ver UI).
- `display`: `1` = pantalla principal, `2` = segunda pantalla (opcional, default 1).

```bash
curl 'http://127.0.0.1:18080/shot?w=960' -o pantalla.jpg
```

### `GET /mouse`
Posición actual del cursor. Regresa `{"ok":true,"x":123,"y":456}`.

### `GET /clipboard`
Lee el portapapeles. Regresa `{"ok":true,"text":"..."}`.

### `GET /apps`
Lista las apps abiertas (visibles). Regresa `{"ok":true,"apps":["Safari","Zoom",...]}`.

### `GET /ping`
Salud del servidor. Regresa `{"ok":true}`.

---

## Actuar

Todos aceptan JSON y regresan `{"ok":true}` (salvo los `*shot`, que regresan JPEG después de actuar).

### `POST /click` — clic izquierdo
```json
{"x": 500, "y": 300}
```

### `POST /dblclick` — doble clic
```json
{"x": 500, "y": 300}
```

### `POST /rclick` — clic derecho
```json
{"x": 500, "y": 300}
```

### `POST /move` — mover el mouse (sin clic)
```json
{"x": 500, "y": 300}
```

### `POST /drag` — arrastrar (para mover ventanas, sliders, seleccionar texto)
```json
{"x1": 100, "y1": 100, "x2": 400, "y2": 400}
```

### `POST /type` — escribir texto
```json
{"text": "Hola mundo"}
```

### `POST /key` — presionar una tecla
```json
{"key": "return"}
```
Teclas comunes: `return`, `tab`, `escape`, `space`, `delete`, `up`, `down`, `left`, `right`, `f5`…

### `POST /hotkey` — combinación de teclas
```json
{"keys": "cmd-c"}
```
Formatos aceptados: `"cmd-c"`, `"cmd+shift-t"`, `"ctrl,alt,del"`. Modificadores: `cmd`, `shift`, `ctrl`/`control`, `alt`/`option`.

### `POST /scroll` — scroll en la posición actual del mouse
```json
{"dy": -5}
```
`dy` negativo = hacia abajo, positivo = hacia arriba.

### `POST /clipboard` — escribir al portapapeles
```json
{"text": "texto a pegar"}
```
Luego usa `cmd-v` (hotkey) para pegarlo donde quieras.

### `POST /launch` — abrir una app
```json
{"app": "Safari"}
```

### `POST /focus` — traer una app al frente
```json
{"app": "Zoom"}
```

---

## Combinados (actuar + ver en una sola llamada)

Ideales para el ciclo "haz algo y verifica". Aceptan los mismos parámetros que su versión simple, más `w` (ancho de captura) y `wait` (segundos a esperar antes de capturar, default 0.5).

### `POST /clickshot`
```json
{"x": 500, "y": 300, "w": 960}
```
Hace clic y regresa la captura JPEG resultante.

### `POST /typeshoot`
```json
{"text": "hola", "w": 960}
```

### `POST /keyshot`
```json
{"key": "return", "w": 960}
```

---

## Flujo típico para una IA

1. `GET /shot?w=960` → ver la pantalla.
2. Localizar el elemento (botón, campo, etc.) y sus coordenadas.
3. `POST /clickshot` con las coordenadas → actuar y ver el resultado en una sola llamada.
4. Repetir hasta completar la tarea.

### Ejemplo en Python

```python
import requests, io
from PIL import Image

BASE = "http://100.x.x.x:18080"  # IP Tailscale de la Mac

def ver():
    r = requests.get(f"{BASE}/shot", params={"w": 960}, timeout=30)
    return Image.open(io.BytesIO(r.content))

def clic(x, y):
    r = requests.post(f"{BASE}/clickshot", json={"x": x, "y": y}, timeout=60)
    return Image.open(io.BytesIO(r.content))

# Ver, luego hacer clic en (500, 300) y ver el resultado
img = ver()
img2 = clic(500, 300)
```

### Ejemplo en curl

```bash
# Ver
curl 'http://100.x.x.x:18080/shot?w=960' -o ver.jpg
# Clic + ver resultado
curl -X POST http://100.x.x.x:18080/clickshot \
  -H 'Content-Type: application/json' \
  -d '{"x":500,"y":300}' -o resultado.jpg
```

---

## Seguridad

- El servidor **solo escucha en la IP de Tailscale** (o 127.0.0.1). Solo dispositivos de tu red Tailscale pueden llegar a él.
- No hay contraseñas: la red Tailscale es la autenticación.
- Nunca expongas el puerto a internet.