# Captain Claude API v3

API para interactuar con Claude Code desde aplicaciones móviles/web.

## Información General

| Campo | Valor |
|-------|-------|
| **Servidor** | ARCHITECT (69.62.126.110) |
| **Puerto** | 3030 |
| **Protocolo** | HTTP + WebSocket |
| **Dominio externo** | captain.tzzrarchitect.me |
| **Ubicación código** | `/home/architect/captain-claude/apps/captain-mobile-v2/backend/captain_api_v3.py` |

## Autenticación

JWT Bearer Token. Obtener via `/auth/login`.

```bash
curl -X POST https://captain.tzzrarchitect.me/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"***"}'
```

Respuesta:
```json
{
  "token": "eyJ...",
  "username": "admin"
}
```

## Endpoints REST

### GET /health
Estado del servicio.

```json
{"status": "ok", "version": "3.0.0"}
```

### POST /auth/login
Autenticación.

**Request:**
```json
{
  "username": "string",
  "password": "string"
}
```

**Response:**
```json
{
  "token": "string",
  "username": "string"
}
```

### GET /sessions
Lista sesiones activas. Requiere Bearer token.

**Response:**
```json
[
  {
    "session_id": "abc123...",
    "name": "Mi sesión"
  }
]
```

### POST /sessions
Crear nueva sesión. Requiere Bearer token.

**Request:**
```json
{
  "name": "Nombre de la sesión"
}
```

**Response:**
```json
{
  "session_id": "abc123...",
  "name": "Nombre de la sesión"
}
```

## WebSocket

### Endpoint
```
wss://captain.tzzrarchitect.me/ws/chat
```

### Flujo de conexión

1. Conectar al WebSocket
2. Enviar autenticación:
   ```json
   {"type": "auth", "token": "eyJ..."}
   ```
3. Recibir confirmación con sesiones existentes:
   ```json
   {
     "type": "init",
     "sessions": [{"session_id": "...", "name": "..."}]
   }
   ```

### Mensajes Cliente → Servidor

#### Crear sesión
```json
{
  "type": "create_session",
  "name": "Nombre de la sesión"
}
```

#### Conectar a sesión existente
```json
{
  "type": "connect_session",
  "session_id": "abc123..."
}
```

#### Enviar mensaje a Claude
```json
{
  "type": "message",
  "content": "Hola Claude"
}
```

### Mensajes Servidor → Cliente

#### Sesión creada
```json
{
  "type": "session_created",
  "session_id": "abc123...",
  "name": "Nombre"
}
```

#### Conectado a sesión
```json
{
  "type": "session_connected",
  "session_id": "abc123...",
  "name": "Nombre"
}
```

#### Output de Claude (streaming)
```json
{
  "type": "output",
  "content": "Texto de respuesta..."
}
```

#### Respuesta completada
```json
{
  "type": "done",
  "session_id": "uuid-de-claude"
}
```

#### Error
```json
{
  "type": "error",
  "message": "Descripción del error"
}
```

## Arquitectura

```
┌─────────────┐     HTTPS/WSS      ┌─────────────┐
│ App Móvil   │ ◄────────────────► │ Caddy       │
│ (Flutter)   │                    │ (reverse    │
└─────────────┘                    │  proxy)     │
                                   └──────┬──────┘
                                          │ :3030
                                   ┌──────▼──────┐
                                   │ Captain API │
                                   │ v3 (uvicorn)│
                                   └──────┬──────┘
                                          │ subprocess
                                   ┌──────▼──────┐
                                   │ Claude Code │
                                   │ (claude -p) │
                                   └─────────────┘
```

## Notas

- **Sin screen**: v3 usa `claude -p` directamente como subprocess, no sesiones screen
- **Session ID**: El `session_id` inicial es temporal. Después del primer mensaje, se actualiza con el UUID real de Claude para poder hacer `--resume`
- **Streaming**: Las respuestas se envían en tiempo real vía WebSocket
- **Concurrencia**: Una sesión solo procesa un mensaje a la vez

## Servicio systemd

```ini
[Unit]
Description=Captain Claude API v3
After=network.target

[Service]
Type=simple
User=architect
WorkingDirectory=/home/architect/captain-claude/apps/captain-mobile-v2/backend
ExecStart=/home/architect/captain-claude/apps/captain-mobile-v2/backend/venv/bin/uvicorn captain_api_v3:app --host 0.0.0.0 --port 3030
Restart=always

[Install]
WantedBy=multi-user.target
```

---
*Última actualización: 2026-01-21*