# Spec: outline-api-client

## ADDED Requirements

### Requirement: Configuración por variables de entorno
El sistema SHALL configurar el cliente de Outline a partir de las variables de entorno `OUTLINE_URL` (URL base de la instancia) y `OUTLINE_API_KEY` (token de API).

#### Scenario: Cliente configurado correctamente
- **WHEN** las variables `OUTLINE_URL` y `OUTLINE_API_KEY` están definidas en el entorno
- **THEN** el cliente construye las peticiones contra la URL base indicada y autentica con el token provisto

#### Scenario: Variables de entorno ausentes
- **WHEN** `OUTLINE_URL` o `OUTLINE_API_KEY` no están definidas al invocar una herramienta
- **THEN** el sistema responde con un mensaje de error descriptivo indicando la configuración faltante

### Requirement: Petición POST genérica autenticada
El cliente HTTP SHALL implementar un método genérico para realizar peticiones POST a los endpoints de la API de Outline, incluyendo el header `Authorization: Bearer <TOKEN>` y el body en formato JSON.

#### Scenario: Petición autenticada
- **WHEN** el cliente envía una petición a cualquier endpoint de la API de Outline
- **THEN** la petición incluye el header `Authorization: Bearer` con el token configurado y el payload serializado como JSON

#### Scenario: Error de la API de Outline
- **WHEN** la API de Outline responde con un código HTTP de error
- **THEN** el sistema propaga un error descriptivo (incluyendo el código y el mensaje de la API) hacia el llamador

### Requirement: Herramienta outline_list_collections
La herramienta `outline_list_collections` SHALL invocar el endpoint `/api/collections.list` y devolver el ID, el nombre y la descripción de cada colección.

#### Scenario: Listado de colecciones exitoso
- **WHEN** se invoca `outline_list_collections` sin parámetros
- **THEN** la herramienta devuelve la lista de colecciones con sus campos `id`, `name` y `description`

### Requirement: Herramienta outline_search
La herramienta `outline_search` SHALL invocar el endpoint `/api/documents.search` recibiendo el parámetro `query` y devolver los resultados de la búsqueda.

#### Scenario: Búsqueda con resultados
- **WHEN** se invoca `outline_search` con un `query` válido
- **THEN** la herramienta devuelve los documentos coincidentes con su información relevante (título, id y extracto)

#### Scenario: Búsqueda sin resultados
- **WHEN** se invoca `outline_search` con un `query` que no coincide con ningún documento
- **THEN** la herramienta devuelve una lista vacía sin error

### Requirement: Herramienta outline_get_document
La herramienta `outline_get_document` SHALL invocar el endpoint `/api/documents.info` recibiendo el parámetro `id` y devolver el título y el texto del documento en formato Markdown.

#### Scenario: Lectura de documento existente
- **WHEN** se invoca `outline_get_document` con el `id` de un documento existente
- **THEN** la herramienta devuelve el título del documento y su contenido en Markdown

#### Scenario: Documento inexistente
- **WHEN** se invoca `outline_get_document` con un `id` que no corresponde a ningún documento
- **THEN** la herramienta devuelve un error indicando que el documento no fue encontrado

### Requirement: Herramienta outline_create_document
La herramienta `outline_create_document` SHALL invocar el endpoint `/api/documents.create` recibiendo los parámetros `title`, `text` (Markdown) y `collection_id`, y devolver la información del documento creado.

#### Scenario: Creación de documento exitosa
- **WHEN** se invoca `outline_create_document` con `title`, `text` y un `collection_id` válido
- **THEN** la herramienta crea el documento en la colección indicada y devuelve su `id` y `title`