📦 @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

npm install @minervajs/http-transport

---

🚀 Quick Start

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?)

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

client.post(url, body, options?)

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

client.request(config)

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

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

Bearer Token

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

API Key

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

HMAC Signature

Automatically signs the JSON payload.

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

Adds the header:

X-Signature: <computed-hmac>

---

🔁 Retry Strategy

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

{
  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

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

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