Metadata-Version: 2.4
Name: aranda-skills
Version: 0.1.0
Summary: Cliente Python para consumir las skills de la API de Aranda ASMS
Author-email: Miguel <miguelmontealegre808@gmail.com>
License: Proprietary
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# aranda-skills

Cliente Python para consumir las **skills de la API de Aranda ASMS** como simples
funciones. El desarrollador no maneja URLs, headers ni tokens en cada llamada:
configura una vez y llama funciones.

Cada skill del directorio `skills/` está expuesta como una función del paquete
`aranda_skills`.

## Instalación

```bash
pip install aranda-skills
```

Desde el repositorio (modo editable, para desarrollo):

```bash
pip install -e .
```

## Configuración

La conexión (URL base, token, SSL, timeout) se resuelve en este orden de
prioridad:

1. Parámetros pasados explícitamente.
2. Variables de entorno con prefijo `ARANDA_`.
3. Archivo `.env` en el directorio de trabajo.
4. Valores por defecto.

### Opción A — variables de entorno / `.env`

```dotenv
ARANDA_BASE_URL=https://proyectos.arandasoft.com/asmsapi/api/v9
ARANDA_TOKEN=Bearer eyJ0...
# Opcionales:
ARANDA_VERIFY_SSL=false
ARANDA_TIMEOUT=30
```

No hace falta nada más; las funciones funcionan directamente:

```python
import aranda_skills as aranda

proyectos = aranda.get_projects()
```

### Opción B — en código

```python
import aranda_skills as aranda

aranda.configure(
    base_url="https://proyectos.arandasoft.com/asmsapi/api/v9",
    token="Bearer eyJ0...",   # el prefijo "Bearer " es opcional
)

proyectos = aranda.get_projects()
```

## Uso

```python
import aranda_skills as aranda

aranda.configure(token="Bearer eyJ0...")

# Catálogos
aranda.get_item_types()
aranda.get_urgency()
aranda.get_impact()
aranda.get_registry_types()

# Navegación de configuración
proyectos  = aranda.get_projects()
servicios  = aranda.get_services(project_id=1, item_type=1)
categorias = aranda.get_categories_by_service(item_type=1, service_id=4)
modelo     = aranda.get_model(item_type=1, category_id=17, service_id=4)
estados    = aranda.get_states(model_id=2, item_type=1)

# Personas
companias = aranda.get_companies(project_id=1, item_type=1)
clientes  = aranda.get_customers(project_id=1, item_type=1, company_id=3, service_id=4)
grupos    = aranda.get_groups_by_state(service_id=4, state_id=110)
resp      = aranda.get_responsible(group_id=10, project_id=1)

# Crear un caso
caso = aranda.create_item(
    author_id=682,
    category_id=17,
    company_id=3,
    customer_id=494,
    description="No hay conexión a internet en piso 3",
    item_type=1,          # 1=Incidente, 2=Problema, 3=Cambio, 4=Requerimiento
    model_id=2,
    project_id=1,
    service_id=4,
    state_id=2,
    subject="Sin internet",
    urgency_id=5,         # opcional
)
```

## Múltiples instancias / multi-tenant

Si necesitas hablar con varias instancias de Aranda a la vez, crea clientes
independientes y pásalos con `client=`:

```python
from aranda_skills import ArandaClient, get_projects

cli_a = ArandaClient(base_url="https://instancia-a/...", token="token-a")
cli_b = ArandaClient(base_url="https://instancia-b/...", token="token-b")

get_projects(client=cli_a)
get_projects(client=cli_b)

# Como context manager (cierra la conexión al salir):
with ArandaClient(token="...") as cli:
    get_projects(client=cli)
```

## Manejo de errores

```python
from aranda_skills import ArandaAPIError, ArandaConfigError
import aranda_skills as aranda

try:
    aranda.get_projects()
except ArandaConfigError:
    ...  # falta el token o la configuración
except ArandaAPIError as e:
    print(e.status_code, e.body)  # la API respondió con error HTTP
```

## Skills disponibles

| Función | Descripción |
|---|---|
| `get_item_types()` | Tipos de caso disponibles |
| `get_registry_types()` | Catálogo de tipos de registro |
| `get_urgency()` | Catálogo de urgencia |
| `get_impact()` | Catálogo de impacto |
| `get_projects(console_type=None)` | Proyectos del usuario |
| `get_services(project_id, item_type, ...)` | Servicios de un proyecto |
| `get_categories_by_service(item_type, service_id)` | Categorías de un servicio |
| `get_model(item_type, category_id, service_id)` | Modelo de flujo de trabajo |
| `get_states(model_id, item_type, state_id=None, item_id=None)` | Estados / transiciones |
| `get_companies(project_id, item_type)` | Compañías de un proyecto |
| `get_customers(project_id, item_type, company_id, service_id, ...)` | Clientes finales |
| `get_groups_by_state(service_id, state_id)` | Grupos de especialistas |
| `get_responsible(group_id, project_id)` | Especialistas de un grupo |
| `get_reasons_for_state(state_id)` | Razones para un estado |
| `get_additional_fields(category_id, item_type, model_id, state_id, ...)` | Campos personalizados |
| `search_cis(project_id, item_type, service_id, ...)` | Elementos de Configuración (CIs) |
| `create_item(...)` | Crea un caso |

Todas aceptan el argumento opcional `client=ArandaClient(...)`.

## Desarrollo

```bash
pip install -e ".[dev]"
pytest -q
```
