62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
# 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`
|