sinapse-ai 5.0.8 → 6.0.1

package/docs/es/api/squads-api.md

@@ -1,753 +0,0 @@
-<!-- Traduccion: ES | Original: /docs/en/api/squads-api.md | Sincronizacion: 2026-01-26 -->
-
-# Referencia de la API de Squads
-
-API REST para sincronizar squads con SINAPSE y descubrir squads del marketplace.
-
-## Vision General
-
-La API de Squads permite:
-
-- **Sync**: Enviar squads locales a la nube de SINAPSE
-- **Marketplace**: Descubrir y explorar squads publicos
-- **Gestion**: Actualizar visibilidad, eliminar squads
-
-**URL Base**: `https://api.sinapse.ai`
-
-## Autenticacion
-
-Todos los endpoints autenticados requieren:
-
-### Clave API (Recomendado para CLI)
-
-```bash
-Authorization: Bearer sk_tu_clave_api
-```
-
-### Token JWT (Aplicaciones web)
-
-```bash
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-```
-
-Obtiene tu clave API de: https://sinapse.ai/settings/api-keys
-
-## Endpoints
-
-### Sincronizar Squad
-
-Envia una definicion de squad a SINAPSE.
-
-```
-POST /api/squads/sync
-```
-
-**Autenticacion**: Requerida
-
-**Cuerpo de la Solicitud**:
-
-| Campo                   | Tipo    | Requerido | Descripcion                                        |
-| ----------------------- | ------- | --------- | -------------------------------------------------- |
-| `squadData`             | object  | Si        | Datos del manifiesto del squad                     |
-| `squadData.name`        | string  | Si        | Nombre del squad                                   |
-| `squadData.version`     | string  | Si        | Version semantica                                  |
-| `squadData.description` | string  | No        | Descripcion del squad                              |
-| `squadData.author`      | string  | No        | Nombre del autor                                   |
-| `squadData.components`  | object  | No        | Componentes del squad                              |
-| `isPublic`              | boolean | No        | Hacer visible publicamente (predeterminado: false) |
-| `isOfficial`            | boolean | No        | Marcar como oficial (solo admin)                   |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl -X POST https://api.sinapse.ai/api/squads/sync \
-  -H "Authorization: Bearer sk_tu_clave_api" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "squadData": {
-      "name": "mi-squad",
-      "version": "1.0.0",
-      "description": "Mi squad increible",
-      "sinapse": {
-        "minVersion": "2.1.0",
-        "type": "squad"
-      },
-      "components": {
-        "agents": ["greeter-agent"],
-        "tasks": ["greet-user"]
-      }
-    },
-    "isPublic": true
-  }'
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": {
-    "squad_id": "mi-squad",
-    "action": "created",
-    "version": "1.0.0",
-    "is_public": true
-  },
-  "duration_ms": 45
-}
-```
-
-**Respuesta de Error** (400):
-
-```json
-{
-  "success": false,
-  "error": "Validacion fallida: nombre es requerido"
-}
-```
-
----
-
-### Sincronizacion por Lotes
-
-Sincroniza multiples squads en una solicitud.
-
-```
-POST /api/squads/sync/batch
-```
-
-**Autenticacion**: Requerida
-
-**Cuerpo de la Solicitud**:
-
-| Campo      | Tipo    | Requerido | Descripcion                                             |
-| ---------- | ------- | --------- | ------------------------------------------------------- |
-| `squads`   | array   | Si        | Array de objetos de datos de squad                      |
-| `isPublic` | boolean | No        | Hacer todos los squads publicos (predeterminado: false) |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl -X POST https://api.sinapse.ai/api/squads/sync/batch \
-  -H "Authorization: Bearer sk_tu_clave_api" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "squads": [
-      {
-        "name": "squad-uno",
-        "version": "1.0.0",
-        "description": "Primer squad"
-      },
-      {
-        "name": "squad-dos",
-        "version": "2.0.0",
-        "description": "Segundo squad"
-      }
-    ],
-    "isPublic": false
-  }'
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": {
-    "total": 2,
-    "created": 2,
-    "updated": 0,
-    "skipped": 0,
-    "failed": 0,
-    "errors": [],
-    "duration_ms": 120
-  }
-}
-```
-
-**Respuesta de Falla Parcial** (200):
-
-```json
-{
-  "success": false,
-  "data": {
-    "total": 2,
-    "created": 1,
-    "updated": 0,
-    "skipped": 0,
-    "failed": 1,
-    "errors": [
-      {
-        "index": 1,
-        "squad_name": "squad-dos",
-        "error": "Validacion fallida: version es requerida"
-      }
-    ],
-    "duration_ms": 85
-  }
-}
-```
-
----
-
-### Listar Squads Publicos (Marketplace)
-
-Explora los squads disponibles en el marketplace.
-
-```
-GET /api/squads
-```
-
-**Autenticacion**: Opcional
-
-**Parametros de Consulta**:
-
-| Parametro  | Tipo    | Predeterminado | Descripcion                       |
-| ---------- | ------- | -------------- | --------------------------------- |
-| `page`     | number  | 1              | Numero de pagina                  |
-| `limit`    | number  | 20             | Items por pagina (max: 100)       |
-| `tags`     | string  | -              | Filtro de tags separados por coma |
-| `author`   | string  | -              | Filtrar por autor                 |
-| `search`   | string  | -              | Buscar en nombre/descripcion      |
-| `official` | boolean | -              | Filtrar solo squads oficiales     |
-
-**Ejemplo de Solicitud**:
-
-```bash
-# Listar todos los squads publicos
-curl https://api.sinapse.ai/api/squads
-
-# Buscar con filtros
-curl "https://api.sinapse.ai/api/squads?tags=devops,automation&search=deploy&official=true&limit=10"
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": [
-    {
-      "id": "550e8400-e29b-41d4-a716-446655440000",
-      "squad_id": "devops-squad",
-      "name": "devops-squad",
-      "version": "2.1.0",
-      "description": "Squad de automatizacion DevOps",
-      "author": "SinapseAI",
-      "tags": ["devops", "automation", "ci-cd"],
-      "is_public": true,
-      "is_official": true,
-      "created_at": "2025-12-01T10:00:00Z",
-      "updated_at": "2025-12-15T14:30:00Z"
-    }
-  ],
-  "pagination": {
-    "page": 1,
-    "limit": 20,
-    "total": 45,
-    "totalPages": 3,
-    "hasMore": true
-  }
-}
-```
-
----
-
-### Listar Mis Squads
-
-Lista squads propiedad de tu workspace.
-
-```
-GET /api/squads/mine
-```
-
-**Autenticacion**: Requerida
-
-**Parametros de Consulta**:
-
-| Parametro | Tipo   | Predeterminado | Descripcion      |
-| --------- | ------ | -------------- | ---------------- |
-| `page`    | number | 1              | Numero de pagina |
-| `limit`   | number | 20             | Items por pagina |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl https://api.sinapse.ai/api/squads/mine \
-  -H "Authorization: Bearer sk_tu_clave_api"
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": [
-    {
-      "id": "550e8400-e29b-41d4-a716-446655440001",
-      "squad_id": "mi-squad-privado",
-      "name": "mi-squad-privado",
-      "version": "1.0.0",
-      "description": "Mi squad interno",
-      "is_public": false,
-      "is_official": false,
-      "sync_status": "synced",
-      "last_synced_at": "2025-12-20T08:00:00Z"
-    }
-  ],
-  "pagination": {
-    "page": 1,
-    "limit": 20,
-    "total": 3,
-    "totalPages": 1,
-    "hasMore": false
-  }
-}
-```
-
----
-
-### Obtener Detalles del Squad
-
-Obtiene informacion detallada sobre un squad especifico.
-
-```
-GET /api/squads/:id
-```
-
-**Autenticacion**: Opcional (requerida para squads privados)
-
-**Parametros de Ruta**:
-
-| Parametro | Tipo   | Descripcion               |
-| --------- | ------ | ------------------------- |
-| `id`      | string | UUID del squad o squad_id |
-
-**Ejemplo de Solicitud**:
-
-```bash
-# Por squad_id
-curl https://api.sinapse.ai/api/squads/devops-squad
-
-# Por UUID
-curl https://api.sinapse.ai/api/squads/550e8400-e29b-41d4-a716-446655440000
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "squad_id": "devops-squad",
-    "name": "devops-squad",
-    "version": "2.1.0",
-    "description": "Squad de automatizacion DevOps para pipelines CI/CD",
-    "author": "SinapseAI",
-    "license": "MIT",
-    "slash_prefix": "devops",
-    "tags": ["devops", "automation", "ci-cd"],
-    "is_public": true,
-    "is_official": true,
-    "manifest": {
-      "name": "devops-squad",
-      "version": "2.1.0",
-      "sinapse": {
-        "minVersion": "2.1.0",
-        "type": "squad"
-      },
-      "components": {
-        "agents": ["deploy-agent", "monitor-agent"],
-        "tasks": ["deploy-app", "check-health"]
-      }
-    },
-    "created_at": "2025-12-01T10:00:00Z",
-    "updated_at": "2025-12-15T14:30:00Z"
-  }
-}
-```
-
-**Respuesta de Error** (404):
-
-```json
-{
-  "success": false,
-  "error": "Squad no encontrado"
-}
-```
-
----
-
-### Actualizar Squad
-
-Actualiza la configuracion de visibilidad del squad.
-
-```
-PATCH /api/squads/:id
-```
-
-**Autenticacion**: Requerida (solo propietario)
-
-**Parametros de Ruta**:
-
-| Parametro | Tipo   | Descripcion               |
-| --------- | ------ | ------------------------- |
-| `id`      | string | UUID del squad o squad_id |
-
-**Cuerpo de la Solicitud**:
-
-| Campo      | Tipo    | Descripcion                    |
-| ---------- | ------- | ------------------------------ |
-| `isPublic` | boolean | Establecer visibilidad publica |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl -X PATCH https://api.sinapse.ai/api/squads/mi-squad \
-  -H "Authorization: Bearer sk_tu_clave_api" \
-  -H "Content-Type: application/json" \
-  -d '{"isPublic": true}'
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": {
-    "id": "550e8400-e29b-41d4-a716-446655440001",
-    "squad_id": "mi-squad",
-    "name": "mi-squad",
-    "is_public": true,
-    "updated_at": "2025-12-26T10:00:00Z"
-  }
-}
-```
-
----
-
-### Eliminar Squad
-
-Elimina un squad de SINAPSE.
-
-```
-DELETE /api/squads/:id
-```
-
-**Autenticacion**: Requerida (solo propietario)
-
-**Parametros de Ruta**:
-
-| Parametro | Tipo   | Descripcion               |
-| --------- | ------ | ------------------------- |
-| `id`      | string | UUID del squad o squad_id |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl -X DELETE https://api.sinapse.ai/api/squads/mi-squad-antiguo \
-  -H "Authorization: Bearer sk_tu_clave_api"
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "message": "Squad eliminado exitosamente"
-}
-```
-
----
-
-### Validar Squad
-
-Valida datos del squad sin persistir.
-
-```
-POST /api/squads/validate
-```
-
-**Autenticacion**: Opcional
-
-**Cuerpo de la Solicitud**:
-
-| Campo       | Tipo   | Requerido | Descripcion                    |
-| ----------- | ------ | --------- | ------------------------------ |
-| `squadData` | object | Si        | Manifiesto del squad a validar |
-
-**Ejemplo de Solicitud**:
-
-```bash
-curl -X POST https://api.sinapse.ai/api/squads/validate \
-  -H "Content-Type: application/json" \
-  -d '{
-    "squadData": {
-      "name": "test-squad",
-      "version": "1.0.0"
-    }
-  }'
-```
-
-**Respuesta Exitosa** (200):
-
-```json
-{
-  "success": true,
-  "data": {
-    "valid": true,
-    "errors": [],
-    "warnings": ["Falta campo recomendado: description", "Falta campo sinapse.minVersion"]
-  }
-}
-```
-
-**Respuesta de Falla de Validacion** (200):
-
-```json
-{
-  "success": false,
-  "data": {
-    "valid": false,
-    "errors": ["nombre es requerido", "version debe ser semver valido"],
-    "warnings": []
-  }
-}
-```
-
----
-
-## Codigos de Error
-
-| Codigo HTTP | Significado                                       |
-| ----------- | ------------------------------------------------- |
-| 200         | Exito                                             |
-| 400         | Solicitud Incorrecta - Entrada invalida           |
-| 401         | No Autorizado - Autenticacion faltante o invalida |
-| 403         | Prohibido - Permisos insuficientes                |
-| 404         | No Encontrado - El squad no existe                |
-| 500         | Error Interno del Servidor                        |
-
-### Formato de Respuesta de Error
-
-```json
-{
-  "success": false,
-  "error": "Mensaje de error legible"
-}
-```
-
----
-
-## Limites de Tasa
-
-| Plan       | Solicitudes/min | Solicitudes/dia |
-| ---------- | --------------- | --------------- |
-| Gratis     | 60              | 1,000           |
-| Pro        | 300             | 10,000          |
-| Enterprise | Ilimitado       | Ilimitado       |
-
-Headers de limite de tasa:
-
-```
-X-RateLimit-Limit: 60
-X-RateLimit-Remaining: 45
-X-RateLimit-Reset: 1703577600
-```
-
----
-
-## Integracion CLI
-
-El comando `*sync-squad-sinapse` usa esta API:
-
-```bash
-# Sincronizar squad individual
-@squad-creator
-*sync-squad-sinapse ./squads/mi-squad --public
-
-# Sincronizacion por lotes de todos los squads
-*sync-squad-sinapse ./squads/* --public
-```
-
-Configurar clave API:
-
-```bash
-export SINAPSE_API_TOKEN="sk_tu_clave_api"
-```
-
----
-
-## Coleccion Postman
-
-Importa esta coleccion en Postman o Insomnia:
-
-```json
-{
-  "info": {
-    "name": "API de Squads SINAPSE",
-    "description": "API REST para el Marketplace de Squads de SINAPSE",
-    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
-  },
-  "variable": [
-    {
-      "key": "baseUrl",
-      "value": "https://api.sinapse.ai"
-    },
-    {
-      "key": "apiKey",
-      "value": "sk_tu_clave_api"
-    }
-  ],
-  "auth": {
-    "type": "bearer",
-    "bearer": [
-      {
-        "key": "token",
-        "value": "{{apiKey}}"
-      }
-    ]
-  },
-  "item": [
-    {
-      "name": "Sync",
-      "item": [
-        {
-          "name": "Sincronizar Squad",
-          "request": {
-            "method": "POST",
-            "url": "{{baseUrl}}/api/squads/sync",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n  \"squadData\": {\n    \"name\": \"mi-squad\",\n    \"version\": \"1.0.0\",\n    \"description\": \"Mi squad\",\n    \"sinapse\": {\n      \"minVersion\": \"2.1.0\",\n      \"type\": \"squad\"\n    }\n  },\n  \"isPublic\": false\n}"
-            }
-          }
-        },
-        {
-          "name": "Sincronizacion por Lotes",
-          "request": {
-            "method": "POST",
-            "url": "{{baseUrl}}/api/squads/sync/batch",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n  \"squads\": [\n    {\"name\": \"squad-1\", \"version\": \"1.0.0\"},\n    {\"name\": \"squad-2\", \"version\": \"1.0.0\"}\n  ],\n  \"isPublic\": false\n}"
-            }
-          }
-        }
-      ]
-    },
-    {
-      "name": "Marketplace",
-      "item": [
-        {
-          "name": "Listar Squads Publicos",
-          "request": {
-            "method": "GET",
-            "url": {
-              "raw": "{{baseUrl}}/api/squads?page=1&limit=20",
-              "query": [
-                { "key": "page", "value": "1" },
-                { "key": "limit", "value": "20" },
-                { "key": "tags", "value": "devops", "disabled": true },
-                { "key": "search", "value": "", "disabled": true },
-                { "key": "official", "value": "true", "disabled": true }
-              ]
-            }
-          }
-        },
-        {
-          "name": "Obtener Detalles del Squad",
-          "request": {
-            "method": "GET",
-            "url": "{{baseUrl}}/api/squads/devops-squad"
-          }
-        }
-      ]
-    },
-    {
-      "name": "Gestion",
-      "item": [
-        {
-          "name": "Listar Mis Squads",
-          "request": {
-            "method": "GET",
-            "url": "{{baseUrl}}/api/squads/mine"
-          }
-        },
-        {
-          "name": "Actualizar Visibilidad del Squad",
-          "request": {
-            "method": "PATCH",
-            "url": "{{baseUrl}}/api/squads/mi-squad",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n  \"isPublic\": true\n}"
-            }
-          }
-        },
-        {
-          "name": "Eliminar Squad",
-          "request": {
-            "method": "DELETE",
-            "url": "{{baseUrl}}/api/squads/mi-squad"
-          }
-        }
-      ]
-    },
-    {
-      "name": "Validacion",
-      "item": [
-        {
-          "name": "Validar Squad",
-          "request": {
-            "method": "POST",
-            "url": "{{baseUrl}}/api/squads/validate",
-            "header": [
-              {
-                "key": "Content-Type",
-                "value": "application/json"
-              }
-            ],
-            "body": {
-              "mode": "raw",
-              "raw": "{\n  \"squadData\": {\n    \"name\": \"test-squad\",\n    \"version\": \"1.0.0\"\n  }\n}"
-            }
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-Guarda el JSON anterior como `sinapse-squads-api.postman_collection.json` e importa en Postman.
-
----
-
-## Recursos Relacionados
-
-- [Guia de Desarrollo de Squads](../guides/squads-guide.md)
-- [Contribuir Squads](../guides/contributing-squads.md)
-- [Agente @squad-creator](../../../.sinapse-ai/development/agents/squad-creator.md)
-
----
-
-**Version:** 1.0.0 | **Actualizado:** 2025-12-26 | **Story:** SQS-8