npm package: @logocomune/maclookup
Description: Node.js client library for maclookup.app REST API V2
Latest version: 1.0.1

# @logocomune/maclookup

[![npm version](https://img.shields.io/npm/v/@logocomune/maclookup.svg)](https://www.npmjs.com/package/@logocomune/maclookup)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight and efficient Node.js client library for the [maclookup.app REST API V2](https://maclookup.app/api-v2/documentation). 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

```bash
npm install @logocomune/maclookup
```

## Quick Start

```javascript
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](https://maclookup.app/api-v2/plans).
- `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.

```bash
# 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](LICENSE) file for details.