{"id":15553,"library":"btch-http","title":"Lightweight Node.js HTTP Client","description":"btch-http is a lightweight and type-safe HTTP client for Node.js, built directly on the Node.js `https` module, ensuring zero external dependencies. The current stable version is 2.0.3, with recent minor updates following a major version 2.0.0 release. It differentiates itself by offering full TypeScript support out-of-the-box, smart error handling that consolidates network, timeout, and HTTP status code (>=300) errors into a custom `HttpError` class, and comprehensive timeout support. It provides both a quick one-liner `HttpGet` function for simple GET requests with URL encoding and a full-featured `HttpClient` class for more complex interactions involving configurable base URLs, versions, default headers, and POST requests with JSON bodies or custom headers. It requires Node.js >=20.18.1.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/hostinger-bot/btch-http","tags":["javascript","http","https","client","typescript","api"],"install":[{"cmd":"npm install btch-http","lang":"bash","label":"npm"},{"cmd":"yarn add btch-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add btch-http","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only since v2.0.0 and requires Node.js >=20.18.1. This function provides a quick GET with automatic URL parameter appending.","wrong":"const { HttpGet } = require('btch-http');","symbol":"HttpGet","correct":"import { HttpGet } from 'btch-http';"},{"note":"The primary class for creating a reusable HTTP client with configurable base URLs, headers, and methods. ESM-only since v2.0.0.","wrong":"const { HttpClient } = require('btch-http');","symbol":"HttpClient","correct":"import { HttpClient } from 'btch-http';"},{"note":"Custom error class thrown for all HTTP-related issues including network errors, timeouts, HTTP status codes >= 300, and JSON parse failures.","wrong":"const { HttpError } = require('btch-http');","symbol":"HttpError","correct":"import { HttpError } from 'btch-http';"},{"note":"It is best practice to use `import type` for type-only imports to improve compilation and runtime performance in TypeScript.","wrong":"import { HttpClientConfig } from 'btch-http';","symbol":"HttpClientConfig","correct":"import type { HttpClientConfig } from 'btch-http';"}],"quickstart":{"code":"import { HttpGet } from 'btch-http';\n\nconst tiktokVideoUrl = 'https://www.tiktok.com/@omagadsus/video/7025456384175017243';\n\nasync function downloadTikTokData() {\n  try {\n    // The `HttpGet` function automatically appends `?url=...` for the second argument.\n    const data = await HttpGet(\n      'ttdl',\n      tiktokVideoUrl,\n      '1.0.0', // Client version\n      30000,   // Timeout in milliseconds\n      'https://backend1.tioo.eu.org' // Base URL for the endpoint\n    );\n    console.log('Download URL:', data.video);\n    console.log('Raw data:', data);\n  } catch (error) {\n    if (error instanceof Error) {\n      console.error('Failed to download TikTok data:', error.message);\n    } else {\n      console.error('An unknown error occurred:', error);\n    }\n  }\n}\n\ndownloadTikTokData();","lang":"typescript","description":"Demonstrates a quick, one-liner GET request using `HttpGet` to retrieve data from a TikTok video downloader API."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` for `btch-http`.","message":"Version 2.0.0 of `btch-http` switched to being an ESM-only package. CommonJS `require()` statements are no longer supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 20.18.1 or newer.","message":"With version 2.0.0, the package's engine requirement was updated to Node.js `>=20.18.1`. Running on older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Be aware of this automatic URL encoding when using `HttpGet`. For more explicit control over query parameters, consider using the `HttpClient` class and its `get` method.","message":"The `HttpGet` function automatically appends the second URL argument as a query parameter (e.g., `?url=...`) to the endpoint. This implicit behavior might be unexpected if not explicitly known.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always wrap your `btch-http` calls in `try...catch` blocks and use `instanceof HttpError` to specifically handle API-related errors, allowing you to inspect `error.status`, `error.message`, and `error.response`.","message":"btch-http's error handling is strict: it throws an `HttpError` for any HTTP status code >= 300, as well as network errors, timeouts, or JSON parsing failures. This might differ from other HTTP clients that only throw for 5xx status codes.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use ES module import syntax: `import { SymbolName } from 'btch-http';`","cause":"Attempting to use CommonJS `require()` syntax to import `btch-http` in an environment configured for ES modules.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Ensure you are using `import { HttpClient } from 'btch-http';` and your project is configured for ES modules, with a compatible Node.js version.","cause":"Incorrect import of `HttpClient` or attempting to use it in a CommonJS context when the package is ESM-only.","error":"TypeError: btch_http_1.HttpClient is not a constructor"},{"fix":"Verify your internet connection, ensure the target `baseUrl` is correct and accessible, and check firewall settings. The `HttpError` will contain details about the underlying network issue.","cause":"A network connectivity issue, DNS resolution failure, or the target server refused the connection.","error":"Failed to download TikTok data: Network Error (or similar message within try/catch)"}],"ecosystem":"npm"}