npm package: @minervajs/http-transport
Description: Lightweight, dependency-free HTTP/HTTPS transport client for Node.js.\ Designed for extensibility, authentication strategies, and retry handling.
Author: Alexander Enrique Escobar
Latest version: 1.0.0

# 📦 @minervajs/http-transport

Lightweight, dependency-free HTTP/HTTPS transport client for Node.js.\
Designed for extensibility, authentication strategies, and retry
handling.

------------------------------------------------------------------------

## ✨ Features

-   ✅ Native `http` / `https` (no external dependencies)
-   🔁 Built-in retry strategy (fixed or exponential backoff)
-   🔐 Pluggable authentication (Basic, Bearer, API Key, HMAC)
-   🧩 Extensible architecture (Factory & Strategy patterns)
-   📦 JSON-first request/response handling
-   ⚡ Lightweight and production-ready

------------------------------------------------------------------------

## 📥 Installation

``` bash
npm install @minervajs/http-transport
```

------------------------------------------------------------------------

## 🚀 Quick Start

``` js
const { HttpClient } = require('@minervajs/http-transport');

(async () => {
  const client = new HttpClient({
    timeout: 5000,
    retries: 2
  });

  const response = await client.get('https://httpbin.org/get');

  console.log(response.status);
  console.log(response.data);
})();
```

------------------------------------------------------------------------

## 🧠 API Overview

### `new HttpClient(options)`

Creates a new HTTP client instance.

### Options

  --------------------------------------------------------------------------
  Option    Type     Default              Description
  --------- -------- -------------------- ----------------------------------
  timeout   number   3000                 Request timeout in milliseconds

  retries   number   0                    Number of retry attempts

  headers   object   `{}`                 Default headers

  auth      object   `{ type: 'none' }`   Authentication configuration
  --------------------------------------------------------------------------

------------------------------------------------------------------------

## 📡 Available Methods

### `client.get(url, options?)`

``` js
await client.get('https://api.example.com/users');
```

### `client.post(url, body, options?)`

``` js
await client.post('https://api.example.com/users', {
  name: 'John'
});
```

### `client.request(config)`

``` js
await client.request({
  method: 'POST',
  url: 'https://api.example.com/data',
  body: { test: true },
  headers: { 'X-Custom': 'Value' }
});
```

------------------------------------------------------------------------

## 🔐 Authentication

Authentication is handled via the `AuthFactory` pattern.

### Basic Authentication

``` js
const client = new HttpClient({
  auth: {
    type: 'basic',
    username: 'admin',
    password: 'secret'
  }
});
```

### Bearer Token

``` js
const client = new HttpClient({
  auth: {
    type: 'bearer',
    token: 'your-jwt-token'
  }
});
```

### API Key

``` js
const client = new HttpClient({
  auth: {
    type: 'apikey',
    header: 'X-API-KEY',
    value: 'your-api-key'
  }
});
```

### HMAC Signature

Automatically signs the JSON payload.

``` js
const client = new HttpClient({
  auth: {
    type: 'hmac',
    secret: 'your-secret',
    algorithm: 'sha256'
  }
});
```

Adds the header:

    X-Signature: <computed-hmac>

------------------------------------------------------------------------

## 🔁 Retry Strategy

``` js
const client = new HttpClient({
  retries: 2
});
```

### Behavior

-   Retries on thrown errors
-   Supports exponential backoff
-   Total attempts = `retries + 1`

Example:

    retries: 2 → 3 total attempts

------------------------------------------------------------------------

## 📤 Response Format

``` js
{
  status: number,
  headers: object,
  data: any
}
```

If the response body is valid JSON → it is automatically parsed.\
If not → it is returned as a raw string.

------------------------------------------------------------------------

## ❌ Error Handling

``` js
try {
  await client.get('https://httpbin.org/status/404');
} catch (err) {
  console.log(err.name);      // HttpError
  console.log(err.status);    // 404
  console.log(err.response);  // Parsed response body
}
```

------------------------------------------------------------------------

## 🧩 Advanced Example

``` js
const { HttpClient } = require('@minervajs/http-transport');

const client = new HttpClient({
  timeout: 5000,
  retries: 2,
  headers: {
    'X-App': 'MinervaJS'
  },
  auth: {
    type: 'bearer',
    token: 'my-token'
  }
});

(async () => {
  const res = await client.post(
    'https://httpbin.org/post',
    { event: 'webhook-test' }
  );

  console.log(res.data);
})();
```

------------------------------------------------------------------------

## 📄 License

BSD-2-Clause