> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexusproject.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Api

# Nexus API — Guía de Desarrollo

## Setup Rápido

```bash theme={null}
cd api/

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tu SECRET_KEY

# Poblar base de datos con datos de demo
python -m seed

# Iniciar servidor con hot-reload
uvicorn app.main:app --reload --port 8000
```

## Estructura del Proyecto

```
api/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app, CORS, lifespan, routers
│   ├── config.py            # Pydantic BaseSettings (.env)
│   ├── database.py          # SQLAlchemy async engine + session + auto-migrate
│   │
│   ├── models/              # SQLAlchemy ORM models
│   │   ├── user.py          # User (perfil, plan, password hash)
│   │   ├── organization.py  # Organization + Members con roles
│   │   ├── project.py       # Project (slug, descripción, repo)
│   │   ├── skill.py         # SkillDefinition + SkillConfiguration
│   │   ├── environment.py   # EnvironmentProfile (CLI profiles + hooks)
│   │   ├── audit.py         # AuditLog (inmutable)
│   │   ├── subscription.py  # Subscription (Stripe)
│   │   └── api_key.py       # APIKey (para CLI auth)
│   │
│   ├── schemas/             # Pydantic v2 request/response
│   │   ├── auth.py          # Register, Login, Token, UserResponse
│   │   ├── project.py       # Project, Environment, CLIProfile, Skill, ScriptHook
│   │   └── dashboard.py     # DashboardStats, ActivityPoint, AuditEntry
│   │
│   ├── services/            # Lógica de negocio
│   │   ├── auth_service.py        # JWT + bcrypt + register/login
│   │   ├── project_service.py     # CRUD + freemium enforcement
│   │   ├── stats_service.py       # Dashboard aggregations
│   │   ├── plan_enforcement.py    # Límites Free/Premium/Enterprise
│   │   ├── seed_skills.py         # Seed 12 skills al startup
│   │   └── admin_bootstrap.py     # Bootstrap admin enterprise
│   │
│   ├── routers/             # Endpoints REST
│   │   ├── auth.py          # /auth (6 endpoints)
│   │   ├── projects.py      # /projects (9 endpoints)
│   │   ├── skills.py        # /skills (3 endpoints)
│   │   ├── teams.py         # /teams (4 endpoints)
│   │   ├── billing.py       # /billing (5 endpoints)
│   │   ├── audit.py         # /audit (1 endpoint filtrable)
│   │   └── dashboard.py     # /dashboard (3 endpoints)
│   │
│   └── middleware/
│       └── auth.py          # JWT dependency (get_current_user)
│
├── seed.py                  # Script de datos de demo
├── requirements.txt
├── .env.example
└── nexus.db           # SQLite (auto-generada, solo desarrollo)
```

## Endpoints

### Auth (`/api/v1/auth`)

| Método | Ruta | Descripción | Auth |
| - | - | - | - |
| `POST` | `/register` | Crear cuenta + organización | No |
| `POST` | `/login` | Obtener JWT token | No |
| `GET` | `/me` | Perfil del usuario autenticado | Bearer |
| `PUT` | `/me` | Actualizar display\_name, avatar | Bearer |

### Projects (`/api/v1/projects`)

| Método | Ruta | Descripción |
| - | - | - |
| `GET` | `/` | Listar proyectos del usuario |
| `POST` | `/` | Crear proyecto (freemium check) |
| `GET` | `/{slug}` | Detalle con environments + skills |
| `PUT` | `/{slug}` | Actualizar nombre, descripción |
| `DELETE` | `/{slug}` | Soft delete |
| `GET` | `/{slug}/environments` | Listar entornos |
| `POST` | `/{slug}/environments` | Crear entorno con CLI profiles |
| `PUT` | `/{slug}/environments/{name}` | Actualizar entorno |

### Skills (`/api/v1/skills`)

| Método | Ruta | Descripción |
| - | - | - |
| `GET` | `/catalog` | Catálogo global de skills |
| `GET` | `/projects/{slug}` | Skills del proyecto |
| `PUT` | `/projects/{slug}/{skill_id}` | Toggle/configurar skill |

### Audit (`/api/v1/audit`)

| Método | Ruta | Query Params |
| - | - | - |
| `GET` | `/` | `action`, `success`, `project_id`, `limit`, `offset` |

### Dashboard (`/api/v1/dashboard`)

| Método | Ruta | Descripción |
| - | - | - |
| `GET` | `/stats` | Total proyectos, switches hoy, skills 7d, tools |
| `GET` | `/activity?days=7` | Switches por día (para gráfica) |
| `GET` | `/recent?limit=10` | Últimos switches con nombre de proyecto |

### Teams (`/api/v1/teams`)

| Método | Ruta | Descripción |
| - | - | - |
| `GET` | `/members` | Listar miembros de la organización |
| `POST` | `/members` | Invitar miembro (email + rol) |
| `PUT` | `/members/{user_id}` | Cambiar rol (member/admin) |
| `DELETE` | `/members/{user_id}` | Eliminar miembro del equipo |

> **Nota:** El usuario invitado debe tener una cuenta registrada en Nexus. El owner y admins pueden gestionar miembros.

### Billing (`/api/v1/billing`)

| Método | Ruta | Descripción |
| - | - | - |
| `GET` | `/plan-limits` | Límites actuales del plan + uso |
| `GET` | `/subscription` | Estado de la suscripción |
| `POST` | `/create-checkout` | Crear sesión Stripe Checkout |
| `POST` | `/confirm-subscription` | Confirmar pago y activar plan |
| `POST` | `/create-portal` | Abrir portal de facturación Stripe |

## Planes y Límites

| Feature | Free | Premium (\$12/mes) | Enterprise |
| - | - | - | - |
| Proyectos | 3 | 100 | Ilimitado |
| CLI Tools | 5 | Ilimitado | Ilimitado |
| Miembros | 1 | 50 | Ilimitado |
| Skills Premium | ❌ | ✅ | ✅ |
| Script-Runners | ❌ | ✅ | ✅ |
| Gestión de Equipos | ❌ | ✅ | ✅ |
| Audit Cloud | ❌ | ✅ | ✅ |

La lógica de enforcement está centralizada en `services/plan_enforcement.py`.

## Autenticación

```bash theme={null}
# 1. Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme-corp.com","password":"password123"}'

# Response: {"access_token": "eyJ...", "user_id": "...", ...}

# 2. Usar el token
curl http://localhost:8000/api/v1/projects/ \
  -H "Authorization: Bearer eyJ..."
```

## Variables de Entorno

| Variable | Default | Descripción |
| - | - | - |
| `DATABASE_URL` | `sqlite+aiosqlite:///./nexus.db` | Conexión BD |
| `SECRET_KEY` | `change-me...` | Clave para firmar JWT |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440` | Duración del token (24h) |
| `CORS_ORIGINS` | `["http://localhost:3000"]` | Orígenes permitidos |
| `FREE_MAX_PROJECTS` | `3` | Límite de proyectos plan Free |
| `PREMIUM_MAX_PROJECTS` | `100` | Límite de proyectos plan Premium |
| `FREE_MAX_CLI_TOOLS` | `5` | Límite de CLI tools plan Free |
| `PREMIUM_MAX_CLI_TOOLS` | `999999` | Límite de CLI tools plan Premium |
| `FREE_MAX_MEMBERS` | `1` | Límite de miembros plan Free |
| `PREMIUM_MAX_MEMBERS` | `50` | Límite de miembros plan Premium |
| `STRIPE_SECRET_KEY` | — | API key de Stripe (server) |
| `STRIPE_PUBLISHABLE_KEY` | — | API key de Stripe (client) |
| `STRIPE_WEBHOOK_SECRET` | — | Secret para validar webhooks |

## Migración a PostgreSQL

Cambiar una línea en `.env`:

```env theme={null}
# De:
DATABASE_URL=sqlite+aiosqlite:///./nexus.db

# A:
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/nexus
```

> **Nota:** Instalar `asyncpg` adicional: `pip install asyncpg`

## Startup Automático

Al arrancar la app se ejecutan automáticamente:

1. **`init_db()`** — Crea tablas + auto-migra columnas faltantes
2. **`seed_skills()`** — Siembra 12 skills (5 free + 7 premium) si no existen
3. **`bootstrap_admin()`** — Asegura que el admin tenga plan Enterprise


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.