Package Exports

koffi-curl
koffi-curl/dist/index.js
koffi-curl/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (koffi-curl) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Koffi-Curl

Node.js libcurl bindings using koffi with browser TLS/JA3 fingerprint capabilities.

Inspired by curl_cffi
Uses curl-impersonate

✨ Features

🚀 High Performance: Direct libcurl bindings via koffi
🕵️ Browser TLS/JA3 Fingerprint: Simulate Chrome, Firefox, Safari, Edge
🔄 HTTP/2 & HTTP/3: Full modern protocol support
🍪 Cookie Management: Automatic cookie handling with tough-cookie
🔒 SSL/TLS: Advanced SSL configuration and verification
📦 Dual Module: CommonJS and ESM support
🎯 Axios Compatible: Drop-in replacement with familiar API
⚡ Async/Await: Modern Promise-based API
🔧 Proxy Support: HTTP, HTTPS, SOCKS proxies

📦 Installation

npm install koffi-curl

🚀 Quick Start

Basic Usage

ESM (ES Modules)

import { req, libcurlVersion } from "koffi-curl";

console.log("libcurl version:", libcurlVersion());

// Simple GET request
const response = await req.get("https://httpbin.org/get", {
  impersonate: "chrome136"
});

console.log("Status:", response.status);
console.log("Data:", response.data);

CommonJS

const { req, libcurlVersion } = require("koffi-curl");

req.get("https://httpbin.org/get", {
  impersonate: "chrome136"
})
  .then((response) => {
    console.log("Status:", response.status);
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error);
  });

POST Request

import { req } from "koffi-curl";

// JSON data
const response = await req.post("https://httpbin.org/post", {
  name: "John",
  age: 30
}, {
  impersonate: "chrome136",
  headers: {
    "Content-Type": "application/json"
  }
});

// Form data
const formResponse = await req.post("https://httpbin.org/post", 
  "key1=value1&key2=value2", 
  {
    impersonate: "firefox128",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    }
  }
);

🔧 Session Plugin

Use the familiar Session API with curl-impersonate power:

import { CurlSession, logger, LogLevel } from "koffi-curl";

// Enable debug logging
logger.setLevel(LogLevel.DEBUG);

// Create axios instance with cookie support
const axios = new CurlSession({
  baseURL: "https://api.example.com",
  timeout: 10000,
  cookieEnable: true,
  impersonate: "chrome136",
  verifySsl: true
});

// Use like regular axios
const response = await axios.get("/users", {
  params: { page: 1 }
});

const postResponse = await axios.post("/users", {
  name: "John Doe",
  email: "john@example.com"
});

🕵️ Browser Fingerprints

Supported browser fingerprints for impersonation:

Browser	Versions Available
Chrome	chrome99, chrome100, chrome101, chrome104, chrome107, chrome110, chrome116, chrome119, chrome120, chrome123, chrome124, chrome126, chrome127, chrome131, chrome136
Firefox	firefox91, firefox95, firefox98, firefox102, firefox105, firefox109, firefox117, firefox121, firefox128, firefox132, firefox133
Safari	safari15_3, safari15_5, safari15_6_1, safari16, safari16_5, safari17_0, safari17_2_1, safari17_4_1, safari17_5, safari18_0
Edge	edge99, edge101, edge122, edge127

// Example with different browsers
await req.get("https://httpbin.org/headers", { impersonate: "chrome136" });
await req.get("https://httpbin.org/headers", { impersonate: "firefox128" });
await req.get("https://httpbin.org/headers", { impersonate: "safari17_5" });

📝 API Reference

Request Options

const options = {
  method: 'GET',           // HTTP method
  headers: {},             // Custom headers
  data: null,              // Request body (POST, PUT, PATCH)
  params: {},              // URL parameters
  timeout: 30000,          // Timeout in milliseconds
  followRedirects: true,   // Follow HTTP redirects
  maxRedirects: 5,         // Maximum redirect count
  proxy: 'http://...',     // Proxy URL
  userAgent: 'Custom',     // Custom User-Agent
  impersonate: 'chrome136', // Browser fingerprint
  verifySsl: true          // SSL certificate verification
};

Response Object

{
  status: 200,              // HTTP status code
  statusText: 'OK',         // HTTP status text
  headers: {},              // Response headers
  data: '...',              // Response body
  url: 'https://...',       // Final URL (after redirects)
  redirectCount: 0          // Number of redirects followed
}

Request Methods

import { req } from "koffi-curl";

// GET request
const response = await req.get(url, options);

// POST request  
const response = await req.post(url, data, options);

// PUT request
const response = await req.put(url, data, options);

// PATCH request
const response = await req.patch(url, data, options);

// DELETE request
const response = await req.delete(url, options);

// Custom request
const response = await req.request({
  url: 'https://example.com',
  method: 'POST',
  data: { key: 'value' }
});

🔄 Advanced Usage

Proxy Configuration

// HTTP proxy
await req.get("https://httpbin.org/ip", {
  proxy: "http://proxy.example.com:8080"
});

// SOCKS proxy
await req.get("https://httpbin.org/ip", {
  proxy: "socks5://proxy.example.com:1080"
});

// Authenticated proxy
await req.get("https://httpbin.org/ip", {
  proxy: "http://username:password@proxy.example.com:8080"
});

Custom Headers

await req.get("https://httpbin.org/headers", {
  headers: {
    "Authorization": "Bearer token123",
    "X-API-Key": "your-api-key",
    "Accept": "application/json"
  },
  impersonate: "chrome136"
});

const axios = new CurlSession({
  cookieEnable: true,  // Enable automatic cookie handling
  impersonate: "chrome136"
});

// Cookies are automatically managed across requests
await axios.post("/login", { username: "user", password: "pass" });
const profile = await axios.get("/profile"); // Cookies sent automatically

📊 Logging

Control logging output for debugging:

import { logger, LogLevel } from "koffi-curl";

// Set log level
logger.setLevel(LogLevel.DEBUG);   // Verbose debugging
logger.setLevel(LogLevel.INFO);    // General information
logger.setLevel(LogLevel.WARN);    // Warnings only
logger.setLevel(LogLevel.ERROR);   // Errors only

🔒 SSL/TLS Configuration

// Disable SSL verification (not recommended for production)
await req.get("https://self-signed.badssl.com/", {
  verifySsl: false
});

// Custom SSL configuration (advanced)
await req.get("https://example.com", {
  verifySsl: true,
  // Additional SSL options can be configured
});

⚡ Performance Tips

Reuse connections: The library automatically handles connection pooling
Choose appropriate timeouts: Set reasonable timeout values for your use case
Use appropriate fingerprints: Different fingerprints may have different performance characteristics
Enable compression: Most fingerprints automatically support gzip/brotli compression

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/tocha688/koffi-curl.git
cd koffi-curl

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

📄 License

MIT © tocha688

🐛 Issues & Support

Found a bug or need help?

🙏 Acknowledgments

curl_cffi - Python inspiration
curl-impersonate - Core fingerprinting technology
koffi - Node.js FFI library
libcurl - The powerful HTTP library

⭐ Star this repo if you find it useful!

koffi-curl