{"id":15502,"library":"abuseipdb-client","title":"AbuseIPDB Node.js Client","description":"The `abuseipdb-client` is an unofficial Node.js client library designed to interact with the AbuseIPDB API v2. It provides a robust, promise-based interface for checking IP addresses, reporting malicious activity, and managing API interactions. Currently stable at version 2.0.90, the library maintains a frequent release cadence, often issuing multiple patch updates monthly to keep dependencies current. Key differentiators include its TypeScript-first design, comprehensive runtime type checking powered by Zod, and full support for both ECMAScript Modules (ESM) and CommonJS (CJS) environments, though ESM is preferred. It standardizes API responses into a structured object containing headers, results, and explicit error handling properties, abstracting away raw HTTP responses.","status":"active","version":"2.0.90","language":"javascript","source_language":"en","source_url":"https://github.com/arthur-melo/abuseipdb-client","tags":["javascript","typescript","abuseipdb","node"],"install":[{"cmd":"npm install abuseipdb-client","lang":"bash","label":"npm"},{"cmd":"yarn add abuseipdb-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add abuseipdb-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for interacting with the AbuseIPDB API. It is a named export. While CJS is supported, ESM is recommended for modern Node.js applications.","wrong":"const AbuseIPDBClient = require('abuseipdb-client');","symbol":"AbuseIPDBClient","correct":"import { AbuseIPDBClient } from 'abuseipdb-client';"},{"note":"Correct CommonJS import for the named export. Direct default import will fail as there is no default export.","wrong":"import AbuseIPDBClient from 'abuseipdb-client';","symbol":"AbuseIPDBClient","correct":"const { AbuseIPDBClient } = require('abuseipdb-client');"},{"note":"Type import for the structured response object returned by client methods.","symbol":"AbuseIPDBResponse","correct":"import type { AbuseIPDBResponse } from 'abuseipdb-client';"}],"quickstart":{"code":"import { AbuseIPDBClient } from 'abuseipdb-client';\nimport 'dotenv/config'; // Ensure environment variables are loaded if using .env\n\nconst API_KEY = process.env.ABUSEIPDB_API_KEY ?? '';\n\nif (!API_KEY) {\n  console.error('ABUSEIPDB_API_KEY environment variable is not set.');\n  process.exit(1);\n}\n\nconst client = new AbuseIPDBClient(API_KEY);\n\nasync function checkIp() {\n  try {\n    const response = await client.check('127.0.0.1', { maxAgeInDays: 15 });\n\n    const { headers, result, error } = response;\n\n    console.log('API Headers:', headers);\n\n    if (error) {\n      console.error('API Error:', error);\n    } else if (result) {\n      console.log('API Result:', result.data);\n    }\n  } catch (err) {\n    console.error('Client execution error:', err);\n  }\n}\n\ncheckIp();","lang":"typescript","description":"This quickstart demonstrates initializing the `AbuseIPDBClient` with an API key from environment variables and performing an IP check, including structured error handling."},"warnings":[{"fix":"Ensure your Node.js environment is upgraded to version 24 or higher. Alternatively, use an older version of the library that supports your Node.js version, if available.","message":"The library explicitly requires Node.js version 24 or higher due to its `engines` field configuration. Using it with older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Store your AbuseIPDB API key in an environment variable (e.g., `ABUSEIPDB_API_KEY` in a `.env` file) and access it using `process.env.ABUSEIPDB_API_KEY`.","message":"API keys should never be hardcoded directly into your source code. They must be managed securely, typically via environment variables.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always check the `error` property of the response object after any API call. If `error` is defined, it contains details about the API-specific issue, and `result` will be undefined. Handle these errors explicitly.","message":"The client wraps all API responses into a consistent object structure, distinguishing between `result` and `error` properties. It does not throw exceptions for API-level errors (e.g., invalid input, unauthorized access); instead, it populates the `error` object.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Implement a robust rate-limiting strategy in your application. Monitor the `x-ratelimit-remaining` header and respect the `retry-after` header if present to avoid being temporarily blocked.","message":"AbuseIPDB enforces rate limits. The client exposes rate limit information in the `headers` object of the response (e.g., `x-ratelimit-limit`, `x-ratelimit-remaining`, `retry-after`). Exceeding limits will lead to errors.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const { AbuseIPDBClient } = require('abuseipdb-client');`. For ESM, ensure `import { AbuseIPDBClient } from 'abuseipdb-client';` is used (named import).","cause":"Attempting to instantiate the `AbuseIPDBClient` class incorrectly in a CommonJS environment or with an incorrect ESM import.","error":"TypeError: AbuseIPDBClient is not a constructor"},{"fix":"Ensure you pass a valid AbuseIPDB API key string when initializing `new AbuseIPDBClient(yourApiKey)` and that the key is active and has necessary permissions.","cause":"The AbuseIPDB API key was either not provided to the client constructor or is incorrect/expired.","error":"Error: Response code 401 (Unauthorized) - Missing API Key or invalid API Key."},{"fix":"Always validate IP address inputs in your application code before passing them to `abuseipdb-client` methods to ensure they conform to IPv4 or IPv6 standards.","cause":"An invalid IP address string was provided to an API method (e.g., `client.check()`). The API's runtime validation (via Zod) caught the malformed input.","error":"{ errors: [ { detail: 'ipAddress must be a valid IPv4 or IPv6 address', status: 422, source: { parameter: 'ipAddress' } } ] }"}],"ecosystem":"npm"}