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.

$ cp .env.example .env

Install dependencies:

$ npm install

And run the tests:

$ npm run test

Browser Support

AbuseIPDB does not support CORS, and there are no plans in doing so.

Quoting from the official documentation:

CORS headers cannot be set in order to prevent misimplementation. APIv2 keys should be treated as private and are not intented for client side calls.

License

abuseipdb-client is released under the MIT license.