abuseipdb-client

Unofficial AbuseIPDB Node.js client library.

Features

• Implements API v2
• Built with TypeScript
• Runtime type checking (Using Zod)
• Promise API
• ESM and CJS builds

Table of Contents

1. Installation
2. Usage
3. About
4. API
5. Examples
6. Running tests
7. Browser Support
8. License

Installation

$ npm install -S abuseipdb-client

Usage

import { AbuseIPDBClient } from 'abuseipdb-client';

const client = new AbuseIPDBClient('API_KEY');

const response = await client.check('127.0.0.1', { maxAgeInDays: 15 });

console.log(response);

Output

{
  headers: {
    url: 'https://api.abuseipdb.com/api/v2/check?ipAddress=127.0.0.1&maxAgeInDays=15',
    status: 200,
    statusText: 'OK',
    'x-ratelimit-limit': '3000',
    'x-ratelimit-remaining': '2999'
  },
  result: {
    data: {
      ipAddress: '127.0.0.1',
      isPublic: false,
      ipVersion: 4,
      // ...
    }
  }
}

About

This library wraps API responses into a single object, providing a standard structure.

const response = await client.check('127.0.0.1');

const { headers, result, error } = response;

The headers structure contains the AbuseIPDB HTTP headers plus some of the Fetch Response information.

headers: {
  url: string;
  status: string;
  statusText: string;
  'x-ratelimit-limit': string;
  'x-ratelimit-remaining': string;
  'retry-after'?: string;
  'x-ratelimit-reset'?: string;
}

The error structure wraps a JSON-API compliant object, as defined by the docs.

error?: {
  errors?: [
    {
      detail?: string;
      status?: number;
      source?: {
        parameter: string
      }
    }
  ]
}

The result structure wraps the API endpoint response.

result?: APIResponse<T>

The headers object is always populated with the data returned from the API. result and error are exclusive, either one of them is defined for a given response.

const response = await client.check('127.0.0.1');

const { headers, result, error } = response;

if (error) {
  // API returned some error message.
  console.log(error);
}

if (result) {
  // API returned a result response.
  console.log(result);
}

// Headers are defined either way.
console.log(headers);

A more detailed explanation can be found at: examples/abstraction.ts.

API

See API Docs

Examples

See Examples

Running tests

In order to run tests, you will need to create an API Key from AbuseIPDB's dashboard.

Then, clone this repo:

$ git clone https://github.com/arthur-melo/abuseipdb-client

Copy the .env.example file to .env, modifying it with your generated API Key.

Install dependencies:

$ npm install

And run the tests:

$ npm run test

Browser Support

This project was built using libraries that allow browser usage, but as of this commit, AbuseIPDB doesn't support CORS.

This limits how you can interact with the API, given that you need a proxy server in order to contact the service.

I'm not generating browser bundles at the moment, but I decided to keep the supporting code nevertheless.

I'll keep an eye whether the team behind AbuseIPDB adds support for this use case in the future.

License

abuseipdb-client is released under the MIT license.