npm package: @ondarion/soprano
Description: An expert, modern, and ultra-advanced HTTP client engine.
Author: DeltaByte
Latest version: 1.1.0

<div align="center">
  <img src="./soprano.png" alt="Soprano Logo" width="200" />

  # Soprano

  **El Cliente HTTP Definitivo para Entornos Modernos.**

  [![NPM Version](https://img.shields.io/npm/v/@ondarion/soprano?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@ondarion/soprano)
  [![License](https://img.shields.io/npm/l/@ondarion/soprano?style=for-the-badge&color=red)](https://github.com/ondarion/soprano/blob/main/LICENSE)
  [![Build Status](https://img.shields.io/github/actions/workflow/status/ondarion/soprano/ci.yml?style=for-the-badge)](https://github.com/ondarion/soprano)
  [![Downloads](https://img.shields.io/npm/dt/@ondarion/soprano?style=for-the-badge&color=green)](https://www.npmjs.com/package/@ondarion/soprano)
</div>

Soprano no es solo otro cliente HTTP; es un **Motor de Solicitudes (Request Engine)** diseñado para desarrolladores que exigen perfección, robustez y control total sobre sus interacciones de red. Construido desde cero para superar las limitaciones de herramientas tradicionales, Soprano ofrece un sistema elegante y potente que se siente nativo y futurista.

## ¿Por qué Soprano?

Mientras que otros clientes simplemente "hacen peticiones", Soprano orquesta todo un ciclo de vida de comunicación.

*   **Motor Avanzado**: Utiliza su propio `1.1.0-SOPRANO-ULTRA` engine para gestionar el ciclo de vida de cada byte.
*   **Intercepción Inteligente**: Un sistema de middleware (interceptores) que permite manipular solicitudes y respuestas con precisión quirúrgica.
*   **Smart Caching**: Sistema de caché en memoria con TTL (Time-To-Live) para respuestas instantáneas.
*   **Control de Concurrencia**: Cola de peticiones integrada para evitar saturación de red.
*   **Resiliencia Automática**: Sistema de reintentos (Retries) inteligente integrado en el núcleo.
*   **Tipado Dinámico**: Parsea automáticamente JSON, Blobs, Texto o ArrayBuffers.
*   **Cero Dependencias Pesadas**: Ligero, rápido y construido sobre estándares modernos (`fetch` API).

## Instalación

```bash
npm install @ondarion/soprano
```

## Uso Básico

Soprano está diseñado para ser intuitivo pero poderoso.

```javascript
const soprano = require('@ondarion/soprano');

// Una simple petición GET que se siente mágica
async function obtenerDatos() {
    try {
        const respuesta = await soprano.get('https://jsonplaceholder.typicode.com/posts/1');
        console.log('Datos:', respuesta.data);
        console.log('Estado:', respuesta.status);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

obtenerDatos();
```

## Características Avanzadas

### 1. El Sistema de Interceptores

Manipula cada paquete antes de que salga o antes de que llegue a tu código.

```javascript
// Interceptor de Solicitud (Request) - Añade tokens o logs
soprano.interceptors.request.use((config) => {
    console.log(`[Soprano] Iniciando petición a: ${config.url}`);
    config.headers['Authorization'] = 'Bearer MI_TOKEN_SECRETO';
    return config;
});

// Interceptor de Respuesta (Response) - Limpia datos
soprano.interceptors.response.use((respuesta) => {
    // Si la API devuelve { status: 'ok', result: [...] }, podemos devolver directo el result
    if (respuesta.data && respuesta.data.result) {
        respuesta.data = respuesta.data.result;
    }
    return respuesta;
});
```

### 2. Resiliencia y Reintentos (Auto-Retry)

Soprano brilla cuando las cosas van mal. Configura reintentos automáticos para conexiones inestables. Esta es una característica nativa del motor, no un plugin externo.

```javascript
// Si la petición falla, Soprano reintentará automáticamente
await soprano.post('https://api.pagos.com/transaccion', { id: 123 }, {
    retries: 3,        // Intentará 3 veces más si falla (4 intentos total)
    retryDelay: 2000,  // Esperará 2 segundos entre intentos (backoff simple)
    timeout: 5000      // Cancelará si tarda más de 5s por intento
});
```

### 3. Smart Caching (TTL)

Acelera tu aplicación almacenando respuestas automáticamente.

```javascript
// La primera petición va a la red. La segunda (si es < 5s) viene de la caché.
await soprano.get('/api/config', { 
    cache: true, 
    ttl: 5000 
});
```

### 4. Control de Concurrencia y Progreso

Maneja cargas masivas y feedback visual de forma nativa.

```javascript
const downloader = soprano.create({
    concurrency: 2, // Solo 2 descargas simultáneas
    timeout: 30000
});

downloader.get('/archivo-grande.pdf', {
    onDownloadProgress: (progress) => {
        console.log(`Descargado: ${Math.round(progress.progress * 100)}%`);
    }
});
```

### 5. Instancias Personalizadas

Crea "clientes" especializados para diferentes partes de tu API, cada uno con su propia configuración aislada.

```javascript
const clientePagos = soprano.create({
    timeout: 10000,
    headers: { 
        'X-Service-Name': 'ServicioPagos',
        'Content-Type': 'application/json'
    }
});

// Este cliente hereda todo el poder de Soprano pero mantiene su configuración única
await clientePagos.get('https://api.pagos.com/estado');
```

## API de Referencia

### `soprano.request(config)`
El método núcleo. Todos los alias (`get`, `post`, etc.) utilizan esto internamente.

### Alias de Métodos
*   `soprano.get(url, [config])`
*   `soprano.delete(url, [config])`
*   `soprano.head(url, [config])`
*   `soprano.options(url, [config])`
*   `soprano.post(url, data, [config])`
*   `soprano.put(url, data, [config])`
*   `soprano.patch(url, data, [config])`

## Configuración y Rendimiento

El objeto de configuración de Soprano es extensible:

```javascript
{
  timeout: 0, // 0 = Sin límite de tiempo
  headers: { 'Accept': 'application/json, text/plain, */*' },
  retries: 0,
  retryDelay: 1000,
  cache: false, // Smart Cache desactivado por defecto
  ttl: 60000, // 1 minuto de vida para caché
  concurrency: Infinity, // Sin límite de peticiones simultáneas
  responseType: 'json'
}
```

Cada respuesta incluye metadatos de rendimiento (`perf`) para que puedas monitorear la latencia de tu red con precisión.

---

<div align="center">
  <sub>Developed By DeltaByte Softworks</sub>
</div>