{"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,"search_vec":"'2.0.90':45 'abstract':110 'abuseipdb':1,6,19,117 'abuseipdb-cli':5 'activ':36 'address':33 'api':20,39,96 'away':111 'base':28 'cadenc':52 'check':31,74 'cjs':88 'client':3,7,12 'commonj':87 'comprehens':71 'contain':102 'current':41,62 'depend':61 'design':14,70 'differenti':64 'ecmascript':83 'environ':89 'error':107 'esm':85,91 'explicit':106 'first':69 'frequent':50 'full':79 'handl':108 'header':103 'http':113 'includ':65 'interact':16,40 'interfac':29 'ip':32 'issu':54 'javascript':115 'keep':60 'key':63 'librari':13,47 'maintain':48 'malici':35 'manag':38 'modul':84 'month':58 'multipl':55 'node':118 'node.js':2,11 'object':101 'often':53 'patch':56 'power':75 'prefer':93 'promis':27 'promise-bas':26 'properti':109 'provid':23 'raw':112 'releas':51 'report':34 'respons':97,114 'result':104 'robust':25 'runtim':72 'stabl':42 'standard':95 'structur':100 'support':80 'though':90 'type':73 'typescript':68,116 'typescript-first':67 'unoffici':10 'updat':57 'v2':21 'version':44 'zod':77","created_at":"2026-04-21T17:58:31.485547+00:00","updated_at":"2026-04-21T17:58:31.485547+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://www.abuseipdb.com","github":"https://github.com/arthur-melo/abuseipdb-client","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/abuseipdb-client","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}