@logocomune/maclookup

A lightweight and efficient Node.js client library for the maclookup.app REST API V2. Easily retrieve vendor and registration information for any MAC address.

Features

• Full MAC Information: Retrieve company name, address, country, block details, and more.
• Built-in Caching: Support for LRU cache to minimize API calls and improve performance.
• Rate Limit Tracking: Automatically parses and provides rate limit information from the API.
• Error Handling: Detailed error messages including API-specific error codes and information.
• Lightweight: Zero-dependency (besides axios and lru-cache).

Installation

npm install @logocomune/maclookup

Quick Start

const MACLookup = require('@logocomune/maclookup');

// Initialize the client (API key is optional for limited free usage)
const client = new MACLookup('YOUR_API_KEY');

// Recommended: Enable the built-in LRU cache
client.withLRUCache();

client.getMacInfo('00:00:00:01', 
  (response) => {
    const info = response.macInfo;
    if (info.found) {
      console.log(`Company: ${info.company}`);
      console.log(`Country: ${info.country}`);
    } else {
      console.log('MAC address not found in database.');
    }
    
    console.log(`Response Time: ${response.responseTime}ms`);
    console.log(`Source: ${response.source}`); // 'api' or 'cache'
    console.log(`Remaining Requests: ${response.rateLimit.remaining}`);
  },
  (error) => {
    console.error('An error occurred:', error.msg);
  },
  () => {
    console.log('Lookup completed.');
  }
);

API Documentation

new MACLookup(apiKey, timeout, prefixUrl)

Creates a new instance of the API client.

• apiKey (string): Your API key. Get one at maclookup.app.
• timeout (number, default: 5000): Request timeout in milliseconds.
• prefixUrl (string, default: 'https://api.maclookup.app'): Base API URL.

.withLRUCache(max, ttl)

Enables the built-in LRU cache.

• max (number, default: 500): Maximum number of items in the cache.
• ttl (number, default: 3600000): Time-to-live in milliseconds (1 hour default).

.getMacInfo(mac, successCb, errorCb, alwaysCb)

Performs a MAC address lookup.

• mac (string): The MAC address to look up (formats like 00:00:00, 00-00-00, 00.00.00 or 000000 are supported).
• successCb (function): Called on successful request. Receives a ResponseMACInfo object.
• errorCb (function): Called on request error. Receives an ErrorMessage object.
• alwaysCb (function): Called after the request finishes, regardless of success or failure.

Models

ResponseMACInfo

The object returned in the successCb.

• status: 'OK' or 'KO'
• macInfo: Detailed MAC information (see below)
• rateLimit: Current rate limit status
• responseTime: Time taken for the request in ms
• source: 'api' or 'cache'

MACInfo

• found: boolean
• company: string (Company name)
• address: string
• country: string (ISO country code)
• macPrefix: string
• blockStart: string
• blockEnd: string
• blockSize: number
• blockType: string
• updated: string
• isPrivate: boolean

Development & Testing

This project uses Mocha for testing and NYC for coverage.

# Run tests
npm test

# Check coverage
npm run test # Coverage report is displayed after tests

License

This project is licensed under the MIT License - see the LICENSE file for details.