### Install node-ipinfo using npm

Source: https://github.com/ipinfo/node/blob/master/README.md

Install the IPinfo NodeJS client library using npm.

```bash
npm install node-ipinfo
```

--------------------------------

### Install node-ipinfo

Source: https://context7.com/ipinfo/node/llms.txt

Install the library using npm or yarn.

```bash
npm install node-ipinfo
# or
yarn add node-ipinfo
```

--------------------------------

### Install node-ipinfo using yarn

Source: https://github.com/ipinfo/node/blob/master/README.md

Install the IPinfo NodeJS client library using yarn.

```bash
yarn add node-ipinfo
```

--------------------------------

### IPinfoWrapper - Standard API Usage

Source: https://context7.com/ipinfo/node/llms.txt

Demonstrates how to use the IPinfoWrapper class to perform single IP lookups and access various data fields. Includes examples for handling bogon IPs and API errors.

```APIDOC
## IPinfoWrapper - Standard API

The main wrapper class for the full IPinfo API (`https://ipinfo.io`). Provides `lookupIp`, `lookupASN`, `lookupResproxy`, `getBatch`, and `getMap`. Returns rich `IPinfo` objects that include geolocation, ASN details, company, carrier, privacy, abuse, and domain data, plus computed fields such as `countryFlag`, `countryCurrency`, `continent`, and `isEU`.

### Method
```typescript
import { IPinfoWrapper, LruCache, ApiLimitError } from "node-ipinfo";
// CommonJS: const { IPinfoWrapper, LruCache, ApiLimitError } = require("node-ipinfo");

// Custom cache: 10 000 items, 12-hour TTL
const cache = new LruCache({ max: 10_000, ttl: 12 * 60 * 60 * 1000 });

// Constructor: token, cache?, timeout?(ms), i18nData?, baseUrl?
const ipinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    cache,
    10_000 // 10-second timeout
);

// Single IP lookup
const data = await ipinfo.lookupIp("8.8.8.8");
console.log(data.ip);                    // "8.8.8.8"
console.log(data.hostname);              // "dns.google"
console.log(data.city);                  // "Mountain View"
console.log(data.region);               // "California"
console.log(data.country);              // "United States"
console.log(data.countryCode);          // "US"
console.log(data.isEU);                 // false
console.log(data.countryFlag);          // { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" }
console.log(data.countryFlagURL);       // "https://cdn.ipinfo.io/static/images/countries-flags/US.svg"
console.log(data.countryCurrency);      // { code: "USD", symbol: "$" }
console.log(data.continent);            // { code: "NA", name: "North America" }
console.log(data.loc);                  // "37.4056,-122.0775"
console.log(data.postal);              // "94043"
console.log(data.timezone);            // "America/Los_Angeles"
console.log(data.org);                 // "AS15169 Google LLC"
console.log(data.asn);
// {asn: "AS15169", name: "Google LLC", domain: "google.com", route: "8.8.8.0/24", type: "hosting"}
console.log(data.company);
// { name: "Google LLC", domain: "google.com", type: "hosting" }
console.log(data.privacy);
// { vpn: false, proxy: false, tor: false, relay: false, hosting: true, service: "" }
console.log(data.abuse);
// { address: "US, CA, Mountain View, 1600 Amphitheatre Parkway, 94043",
//   country: "United States", countryCode: "US",
//   email: "network-abuse@google.com", name: "Abuse",
//   network: "8.8.8.0/24", phone: "+1-650-253-0000" }
console.log(data.domains);
// { ip: "8.8.8.8", total: 12095, domains: ["hdchina.org", ...] }

// Bogon IPs are resolved locally — no HTTP request is made
const bogon = await ipinfo.lookupIp("192.168.1.1");
console.log(bogon.bogon); // true

// Error handling
try {
    await ipinfo.lookupIp("1.1.1.1");
} catch (err) {
    if (err instanceof ApiLimitError) {
        console.error("Monthly quota exceeded");
    } else {
        console.error("Lookup failed:", err.message);
    }
}
```
```

--------------------------------

### Example Internationalized IP Lookup Response

Source: https://github.com/ipinfo/node/blob/master/README.md

Demonstrates the structure of the response object when internationalization settings are applied, including country details, flags, currency, and continent.

```json
{
  "ip": "8.8.8.8",
  // ...
  "countryCode": 'US',
  "countryFlag": { "emoji": "🇺🇸", "unicode": "U+1F1FA U+1F1F8" },
  "countryFlagURL": 'https://cdn.ipinfo.io/static/images/countries-flags/US.svg',
  "countryCurrency": { "code": "USD", "symbol": "$" },
  "continent": { "code": "NA", "name": "North America" },
  "isEU": false
}
```

--------------------------------

### Get IP Location Information

Source: https://github.com/ipinfo/node/blob/master/README.md

Retrieve latitude and longitude for a given IP address. Ensure you have initialized the IPinfoWrapper with your API token.

```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");

ipinfoWrapper.lookupIp("1.1.1.1").then(response => {
    // '34.0522,-118.2437'
    console.log(response.loc);
});
```

--------------------------------

### Initialize IPinfoWrapper

Source: https://github.com/ipinfo/node/blob/master/README.md

Initialize an instance of IPinfoWrapper with your IPinfo API access token.

```APIDOC
## Initialize IPinfoWrapper

### Description
Initialize an instance of `IPinfoWrapper` with your IPinfo API access token. You can get a token by signing up for a free account at https://ipinfo.io/signup.

### Method
```typescript
new IPinfoWrapper(token: string)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
```

### Response
None

#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Configure Custom LRU Cache

Source: https://context7.com/ipinfo/node/llms.txt

Demonstrates how to configure and use a custom LRU cache with specific size and TTL settings. Also shows how to implement a custom cache store like Redis that adheres to the Cache interface.

```typescript
import { IPinfoWrapper, LruCache, Cache } from "node-ipinfo";
import type { Options } from "node-ipinfo"; // re-exported from lru-cache

// Custom LRU settings
const cache = new LruCache({
    max: 10_000,               // max 10 000 entries
    ttl: 6 * 60 * 60 * 1000   // 6-hour TTL
});

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!, cache);

// --- Custom cache implementation (e.g., Redis) ---
class RedisCache implements Cache {
    async get(key: string): Promise<any> {
        const raw = await redisClient.get(key);
        return raw ? JSON.parse(raw) : undefined;
    }
    async set(key: string, data: any): Promise<void> {
        await redisClient.set(key, JSON.stringify(data), "EX", 86400);
    }
}

const redisIpinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    new RedisCache()
);

// Cache keys are versioned internally via IPinfoWrapper.cacheKey()
const cacheKey = IPinfoWrapper.cacheKey("8.8.8.8"); // "8.8.8.8:1"
```

```typescript
import { IPinfoWrapper } from "node-ipinfo";

const i18nData = {
    countries: {
        US: "États-Unis",
        DE: "Allemagne",
        FR: "France"
    },
    countriesFlags: {
        US: { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" },
        DE: { emoji: "🇩🇪", unicode: "U+1F1E9 U+1F1EA" }
    },
    countriesCurrencies: {
        US: { code: "USD", symbol: "$" },
        DE: { code: "EUR", symbol: "€" }
    },
    continents: {
        US: { code: "NA", name: "Amérique du Nord" },
        DE: { code: "EU", name: "Europe" }
    },
    euCountries: ["DE", "FR", "ES", "IT", "NL", "BE", "AT", "PL"]
};

// Constructor: token, cache?, timeout?, i18nData?
const ipinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    undefined,
    undefined,
    i18nData
);

const data = await ipinfo.lookupIp("8.8.8.8");
console.log(data.country);    // "États-Unis"
console.log(data.isEU);       // false
console.log(data.continent);  // { code: "NA", name: "Amérique du Nord" }

const de = await ipinfo.lookupIp("2.16.0.1");
console.log(de.country); // "Allemagne"
console.log(de.isEU);    // true
```

--------------------------------

### Initialize IPinfoWrapper with token

Source: https://github.com/ipinfo/node/blob/master/README.md

Initialize an instance of IPinfoWrapper with your IPinfo API access token. This is required before performing any lookups.

```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
```

```typescript
import { IPinfoWrapper } from "node-ipinfo";
```

--------------------------------

### ApiLimitError Handling

Source: https://context7.com/ipinfo/node/llms.txt

Details the `ApiLimitError` which is thrown when the API rate limit (HTTP 429) is exceeded. It also mentions that other HTTP 4xx/5xx errors result in a standard `Error`. Provides an example of catching `ApiLimitError` for graceful degradation.

```APIDOC
## ApiLimitError — Rate Limit Error Handling

`ApiLimitError` is thrown when the API returns HTTP 429 (monthly quota exceeded). All other HTTP 4xx/5xx errors produce a standard `Error`. Both error types should be caught at call sites.

```typescript
import { IPinfoWrapper, ApiLimitError } from "node-ipinfo";

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!);

// Graceful degradation pattern
async function getCountryCode(ip: string): Promise<string> {
    return ipinfo
        .lookupIp(ip)
        .then((data) => data.countryCode ?? "N/A")
        .catch((err) => {
            if (err instanceof ApiLimitError) {
                console.warn("Rate limit hit — returning fallback");
                return "N/A";
            }
            // Re-throw unexpected errors
            throw err;
        });
}

console.log(await getCountryCode("8.8.8.8")); // "US"
console.log(await getCountryCode("bad-ip"));  // "N/A" (or throws)
```
```

--------------------------------

### Initialize IPinfoLiteWrapper for Lite API

Source: https://github.com/ipinfo/node/blob/master/README.md

Initialize an instance of IPinfoLiteWrapper to use the IPinfo Lite API. Authentication with a token is still required. The Lite API returns a subset of the data available through the Core API.

```typescript
import { IPinfoLiteWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoLiteWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.countryCode)
// US
console.log(ipinfo.country)
// United States
```

--------------------------------

### LRU Cache Configuration

Source: https://context7.com/ipinfo/node/llms.txt

Demonstrates how to configure and use the built-in LRU cache with custom settings for max entries and time-to-live (TTL). It also shows how to implement a custom cache store, like Redis, adhering to the `Cache` interface.

```APIDOC
## LruCache — Built-in LRU Cache

The default cache used by all wrappers. Built on `lru-cache` v7. Configurable via `lru-cache` `Options`. Implements the `Cache` interface (`get(key): any` / `set(key, data): void`) so it can be replaced with any custom store.

```typescript
import { IPinfoWrapper, LruCache, Cache } from "node-ipinfo";
import type { Options } from "node-ipinfo"; // re-exported from lru-cache

// Custom LRU settings
const cache = new LruCache({
    max: 10_000,               // max 10 000 entries
    ttl: 6 * 60 * 60 * 1000   // 6-hour TTL
});

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!, cache);

// --- Custom cache implementation (e.g., Redis) ---
class RedisCache implements Cache {
    async get(key: string): Promise<any> {
        const raw = await redisClient.get(key);
        return raw ? JSON.parse(raw) : undefined;
    }
    async set(key: string, data: any): Promise<void> {
        await redisClient.set(key, JSON.stringify(data), "EX", 86400);
    }
}

const redisIpinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    new RedisCache()
);

// Cache keys are versioned internally via IPinfoWrapper.cacheKey()
const cacheKey = IPinfoWrapper.cacheKey("8.8.8.8"); // "8.8.8.8:1"
```
```

--------------------------------

### Customizing Cache

Source: https://github.com/ipinfo/node/blob/master/README.md

Explains how to configure the LRU cache or implement a custom caching strategy using the `IPCache` interface.

```APIDOC
## Customizing Cache

### Description
This section details how to configure the default LRU cache or implement a custom caching mechanism. The default cache has a length of 1 day and a maximum of 5000 items. You can modify these settings or provide your own cache implementation.

### Method
Constructor parameter for `IPinfoWrapper` or `IPinfoPlusWrapper`.

### Endpoint
N/A (Library configuration)

### Parameters
- `cacheOptions` (Optional): An object to configure the `LruCache` with `max` (maximum number of items) and `ttl` (time to live in milliseconds).
- `cache`: An instance of `LruCache` or a custom implementation adhering to the `IPCache` interface.

### Request Example
```typescript
const { IPinfoWrapper, LruCache } = require("node-ipinfo");

const cacheOptions = {
    max: 5000,
    ttl: 24 * 1000 * 60 * 60 // 1 day in milliseconds
};

const cache = new LruCache(cacheOptions);

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", cache);
```

### Response
N/A (Configuration setting)
```

--------------------------------

### Internationalization (i18n) Configuration

Source: https://context7.com/ipinfo/node/llms.txt

Explains how to customize country names, flags, currencies, continent mappings, and EU member lists by providing an `i18nData` object to the wrapper constructor. This enables localization of IP lookup results.

```APIDOC
## Internationalization (i18n)

All wrapper constructors accept an optional `i18nData` object to override built-in country names, flags, currencies, continent mappings, and EU member lists. This allows returning country names in any language or customizing EU country membership.

```typescript
import { IPinfoWrapper } from "node-ipinfo";

const i18nData = {
    countries: {
        US: "États-Unis",
        DE: "Allemagne",
        FR: "France"
    },
    countriesFlags: {
        US: { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" },
        DE: { emoji: "🇩🇪", unicode: "U+1F1E9 U+1F1EA" }
    },
    countriesCurrencies: {
        US: { code: "USD", symbol: "$" },
        DE: { code: "EUR", symbol: "€" }
    },
    continents: {
        US: { code: "NA", name: "Amérique du Nord" },
        DE: { code: "EU", name: "Europe" }
    },
    euCountries: ["DE", "FR", "ES", "IT", "NL", "BE", "AT", "PL"]
};

// Constructor: token, cache?, timeout?, i18nData?
const ipinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    undefined,
    undefined,
    i18nData
);

const data = await ipinfo.lookupIp("8.8.8.8");
console.log(data.country);    // "États-Unis"
console.log(data.isEU);       // false
console.log(data.continent);  // { code: "NA", name: "Amérique du Nord" }

const de = await ipinfo.lookupIp("2.16.0.1");
console.log(de.country); // "Allemagne"
console.log(de.isEU);    // true
```
```

--------------------------------

### Initialize IPinfoCoreWrapper for Core API

Source: https://github.com/ipinfo/node/blob/master/README.md

Initialize an instance of IPinfoCoreWrapper to use the IPinfo Core API. This API provides comprehensive data including nested geo and AS objects. Authentication with a token is required.

```typescript
import { IPinfoCoreWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoCoreWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.ip);
// 8.8.8.8
console.log(ipinfo.geo);
// { city: 'Mountain View', region: 'California', regionCode: 'CA', country: 'United States', countryCode: 'US', ... }
console.log(ipinfo.as);
// { asn: 'AS15169', name: 'Google LLC', domain: 'google.com', type: 'hosting', ... }
```

--------------------------------

### IPinfoLiteWrapper

Source: https://context7.com/ipinfo/node/llms.txt

A lightweight wrapper for the free IPinfo Lite API. It returns basic geolocation and ASN fields. The `lookupIp` method can be used to look up a specific IP address or the caller's own IP if no argument is provided. It also supports bogon short-circuiting.

```APIDOC
## IPinfoLiteWrapper

### Description
A lightweight wrapper for the free [IPinfo Lite API](https://ipinfo.io/developers/lite-api) (`https://api.ipinfo.io/lite`). Returns basic geolocation and ASN fields. Supports `lookupIp` only; passing no IP resolves the caller's own IP via `"me"`.

### Method Signature
`lookupIp(ip?: string): Promise<IPinfoLite | IPBogon>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { IPinfoLiteWrapper, IPinfoLite, IPBogon } from "node-ipinfo";

const ipinfo = new IPinfoLiteWrapper(process.env.IPINFO_TOKEN!); // Token is optional for Lite API

// Named IP
const data = (await ipinfo.lookupIp("8.8.8.8")) as IPinfoLite;
console.log(data.ip);            // "8.8.8.8"
console.log(data.asn);           // "AS15169"
console.log(data.asName);        // "Google LLC"
console.log(data.asDomain);      // "google.com"
console.log(data.countryCode);   // "US"
console.log(data.country);       // "United States"
console.log(data.continentCode); // "NA"
console.log(data.continent);     // "North America"
console.log(data.isEU);          // false

// Resolve caller's own IP (omit argument or pass undefined)
const me = (await ipinfo.lookupIp()) as IPinfoLite;
console.log(me.countryCode); // e.g. "DE"

// Bogon short-circuit (no HTTP request)
const bogon = (await ipinfo.lookupIp("10.0.0.1")) as IPBogon;
console.log(bogon.bogon); // true
```

### Response
#### Success Response (IPinfoLite)
- **ip** (string) - The IP address.
- **asn** (string) - The Autonomous System Number.
- **asName** (string) - The name of the ASN.
- **asDomain** (string) - The domain of the ASN.
- **countryCode** (string) - The two-letter country code.
- **country** (string) - The full country name.
- **continentCode** (string) - The two-letter continent code.
- **continent** (string) - The full continent name.
- **isEU** (boolean) - Whether the IP address is in the European Union.

#### Success Response (IPBogon)
- **bogon** (boolean) - True if the IP address is a bogon (e.g., private, reserved).

#### Response Example (IPinfoLite)
```json
{
  "ip": "8.8.8.8",
  "asn": "AS15169",
  "asName": "Google LLC",
  "asDomain": "google.com",
  "countryCode": "US",
  "country": "United States",
  "continentCode": "NA",
  "continent": "North America",
  "isEU": false
}
```

#### Response Example (IPBogon)
```json
{
  "bogon": true
}
```
```

--------------------------------

### Error Handling for Lookups

Source: https://github.com/ipinfo/node/blob/master/README.md

Demonstrates how to handle errors that may occur during IP address lookups.

```APIDOC
## Error Handling for Lookups

### Description
Each `lookup` method will throw an error when the lookup does not complete successfully. A program that performs a lookup should catch errors unless it is desirable for the error to bubble up. For example, if your program is performing a lookup to find the country code of an IP you can return "N/A" when catching an error.

### Method
```typescript
.catch(error => { /* handle error */ })
```

### Parameters
None

### Request Example
```typescript
const countryCode = ipinfoWrapper
    .lookupIp("1.1.1.1")
    .then((ipinfo) => ipinfo.countryCode)
    .catch((error) => "N/A");
```

### Response
None

#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Generate IP Map Visualizations with getMap

Source: https://context7.com/ipinfo/node/llms.txt

Use getMap to submit a list of IPs (up to 500,000) for visualization on a world map. The method returns a URL to the generated report. Submitting more than the limit rejects immediately.

```typescript
import { IPinfoWrapper, MapResponse } from "node-ipinfo";

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!);

const result: MapResponse = await ipinfo.getMap(["1.1.1.1", "8.8.8.8", "4.4.4.4"]);
console.log(result.status);     // "Report Generated"
console.log(result.reportUrl);  // "https://ipinfo.io/tools/map/xxxxxxxx"

// Large list — rejected immediately without HTTP call
ipinfo.getMap(new Array(500_001).fill("1.1.1.1"))
    .catch(err => console.error(err.message));
// "You have exceeded maximum IP upload limit per request."
```

--------------------------------

### Configuring Request Timeouts

Source: https://github.com/ipinfo/node/blob/master/README.md

Details how to set custom timeouts for API requests made by the client library.

```APIDOC
## Configuring Request Timeouts

### Description
This section explains how to set a custom timeout for API requests. The default timeout is 5000 milliseconds (5 seconds). Setting the timeout to `0` disables the timeout feature.

### Method
Constructor parameter for `IPinfoWrapper` or `IPinfoPlusWrapper`.

### Endpoint
N/A (Library configuration)

### Parameters
- `timeout`: The timeout duration in milliseconds. A value of `0` disables the timeout.

### Request Example
```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const timeout = 10 * 1000; // 10 seconds

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", undefined, timeout);
```

### Response
N/A (Configuration setting)
```

--------------------------------

### IPinfoWrapper - Standard API Lookup

Source: https://context7.com/ipinfo/node/llms.txt

Use IPinfoWrapper for the full IPinfo API. Configure with a token, optional cache, and timeout. Handles various data fields including geolocation, ASN, company, and privacy details. Bogon IPs are resolved locally. Includes error handling for API limits.

```typescript
import { IPinfoWrapper, LruCache, ApiLimitError } from "node-ipinfo";
// CommonJS: const { IPinfoWrapper, LruCache, ApiLimitError } = require("node-ipinfo");

// Custom cache: 10 000 items, 12-hour TTL
const cache = new LruCache({ max: 10_000, ttl: 12 * 60 * 60 * 1000 });

// Constructor: token, cache?, timeout?(ms), i18nData?, baseUrl?
const ipinfo = new IPinfoWrapper(
    process.env.IPINFO_TOKEN!,
    cache,
    10_000 // 10-second timeout
);

// Single IP lookup
const data = await ipinfo.lookupIp("8.8.8.8");
console.log(data.ip);                    // "8.8.8.8"
console.log(data.hostname);              // "dns.google"
console.log(data.city);                  // "Mountain View"
console.log(data.region);               // "California"
console.log(data.country);              // "United States"
console.log(data.countryCode);          // "US"
console.log(data.isEU);                 // false
console.log(data.countryFlag);          // { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" }
console.log(data.countryFlagURL);       // "https://cdn.ipinfo.io/static/images/countries-flags/US.svg"
console.log(data.countryCurrency);      // { code: "USD", symbol: "$" }
console.log(data.continent);            // { code: "NA", name: "North America" }
console.log(data.loc);                  // "37.4056,-122.0775"
console.log(data.postal);              // "94043"
console.log(data.timezone);            // "America/Los_Angeles"
console.log(data.org);                 // "AS15169 Google LLC"
console.log(data.asn);
// { asn: "AS15169", name: "Google LLC", domain: "google.com", route: "8.8.8.0/24", type: "hosting" }
console.log(data.company);
// { name: "Google LLC", domain: "google.com", type: "hosting" }
console.log(data.privacy);
// { vpn: false, proxy: false, tor: false, relay: false, hosting: true, service: "" }
console.log(data.abuse);
// { address: "US, CA, Mountain View, 1600 Amphitheatre Parkway, 94043",
//   country: "United States", countryCode: "US",
//   email: "network-abuse@google.com", name: "Abuse",
//   network: "8.8.8.0/24", phone: "+1-650-253-0000" }
console.log(data.domains);
// { ip: "8.8.8.8", total: 12095, domains: ["hdchina.org", ...] }

// Bogon IPs are resolved locally — no HTTP request is made
const bogon = await ipinfo.lookupIp("192.168.1.1");
console.log(bogon.bogon); // true

// Error handling
try {
    await ipinfo.lookupIp("1.1.1.1");
} catch (err) {
    if (err instanceof ApiLimitError) {
        console.error("Monthly quota exceeded");
    } else {
        console.error("Lookup failed:", err.message);
    }
}
```

--------------------------------

### Timeout Configuration

Source: https://context7.com/ipinfo/node/llms.txt

Explains how to configure request timeouts using the `timeout` constructor parameter. The default is 5000ms, and setting it to 0 disables timeouts. It also covers per-chunk and total timeout settings for the `getBatch` method.

```APIDOC
## Timeout Configuration

All wrappers accept a `timeout` constructor parameter (milliseconds). The default is `5 000` ms (5 seconds). Pass `0` to disable timeouts entirely. `getBatch` also accepts per-chunk and total timeout parameters independently.

```typescript
import { IPinfoWrapper } from "node-ipinfo";

// 15-second timeout for all single-IP/ASN requests
const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!, undefined, 15_000);

// Disable timeout (e.g., for offline/private environments)
const noTimeout = new IPinfoWrapper(process.env.IPINFO_TOKEN!, undefined, 0);

// getBatch with per-chunk timeout of 10 s and total cap of 60 s
const batch = await ipinfo.getBatch(
    ["1.1.1.1", "8.8.8.8"],
    1000,   // batchSize
    10_000, // batchTimeout per chunk (ms)
    60_000  // timeoutTotal across all chunks (ms); 0 = disabled
);
```
```

--------------------------------

### IPinfoWrapper.getMap

Source: https://context7.com/ipinfo/node/llms.txt

Submits up to 500 000 IPs to IPinfo's mapping tool and returns a URL to a world-map visualization. Rejects immediately if the input exceeds 500 000 entries.

```APIDOC
## IPinfoWrapper.getMap — IP Map Visualization

### Description
Submits up to 500 000 IPs to IPinfo's mapping tool and returns a URL to a world-map visualization. Rejects immediately if the input exceeds 500 000 entries.

### Method
`await ipinfo.getMap(ips: string[])`

### Parameters
#### Path Parameters
- **ips** (array of strings) - Required - A list of IP addresses to visualize on the map. Maximum 500,000 IPs.

### Response
#### Success Response (200)
- **status** (string) - The status of the map generation report.
- **reportUrl** (string) - The URL to the generated world-map visualization.

### Request Example
```typescript
import { IPinfoWrapper, MapResponse } from "node-ipinfo";

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!);

const result: MapResponse = await ipinfo.getMap(["1.1.1.1", "8.8.8.8", "4.4.4.4"]);
console.log(result.status);     // "Report Generated"
console.log(result.reportUrl);  // "https://ipinfo.io/tools/map/xxxxxxxx"

// Large list — rejected immediately without HTTP call
ipinfo.getMap(new Array(500_001).fill("1.1.1.1"))
    .catch(err => console.error(err.message));
// "You have exceeded maximum IP upload limit per request."
```
```

--------------------------------

### Configure Internationalization Settings

Source: https://github.com/ipinfo/node/blob/master/README.md

Customize country names, flags, currencies, and continents for IP lookup responses. The `euCountries` array can also be modified.

```javascript
const { IPinfoWrapper } = require("node-ipinfo");

const internationalization = {
    countries: {
        US: "United States",
        FR: "France",
        BD: "Bangladesh"
        // ...
    },
    countriesFlags: {
        US: { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" },
        AD: { emoji: "🇦🇩", unicode: "U+1F1E6 U+1F1E9" },
        AE: { emoji: "🇦🇪", unicode: "U+1F1E6 U+1F1EA" }
        // ...
    },
    countriesCurrencies: {
        US: { code: "USD", symbol: "$" },
        AD: { code: "EUR", symbol: "€" },
        AE: { code: "AED", symbol: "د.إ" }
        // ...
    },
    continents: {
        US: { code: "NA", name: "North America" },
        BD: { code: "AS", name: "Asia" },
        BE: { code: "EU", name: "Europe" }
        // ...
    },
    euCountries: ["FR", "ES", "BE"]
};

const ipinfoWrapper = new IPinfoWrapper(
    "MY_TOKEN",
    undefined,
    undefined,
    internationalization
);

ipinfoWrapper.lookupIp("8.8.8.8").then((response) => console.log(response));
```

--------------------------------

### IPinfoWrapper.getBatch

Source: https://context7.com/ipinfo/node/llms.txt

Fetches details for multiple IPs and ASNs in a single HTTP request (chunked automatically at 1 000 items per request). Accepts arbitrary IPinfo API URL patterns such as "8.8.8.8/hostname" to return a specific field. Already-cached entries are served from cache without a network call.

```APIDOC
## IPinfoWrapper.getBatch — Bulk IP/ASN Lookup

### Description
Fetches details for multiple IPs and ASNs in a single HTTP request (chunked automatically at 1 000 items per request). Accepts arbitrary IPinfo API URL patterns such as `"8.8.8.8/hostname"` to return a specific field. Already-cached entries are served from cache without a network call.

### Method
`await ipinfo.getBatch(batchInput: string[], batchSize?: number, batchTimeout?: number, timeoutTotal?: number, filter?: boolean)`

### Parameters
#### Path Parameters
- **batchInput** (array of strings) - Required - An array of IPs, ASNs, or IPinfo API URL patterns to look up.
- **batchSize** (number) - Optional - The maximum number of items per batch request (default: 1000, max: 1000).
- **batchTimeout** (number) - Optional - The timeout in milliseconds for each chunk request (default: 5000).
- **timeoutTotal** (number) - Optional - The total timeout in milliseconds for the overall request (0 = disabled).
- **filter** (boolean) - Optional - If true, strips empty or error results from the response (default: false).

### Response
#### Success Response (200)
- **response** (object) - An object where keys are the input identifiers and values are the corresponding lookup results.

### Request Example
```typescript
import { IPinfoWrapper, BatchResponse } from "node-ipinfo";

const ipinfo = new IPinfoWrapper(process.env.IPINFO_TOKEN!);

// Mixed input: IPs, field-scoped IP URLs, ASNs
const batch: BatchResponse = await ipinfo.getBatch(
    ["8.8.8.8/hostname", "1.1.1.1", "AS15169"],
    1000,    // batchSize (default 1000, max 1000)
    5000,    // batchTimeout ms per chunk request (default 5000)
    30_000,  // timeoutTotal ms overall (0 = disabled)
    false    // filter: if true, strips empty/error results
);

console.log(batch["8.8.8.8/hostname"]);  // "dns.google"
console.log(batch["1.1.1.1"]);
// { ip: "1.1.1.1", city: "...", country: "Australia", countryCode: "AU", ... }
console.log(batch["AS15169"]);
// { asn: "AS15169", name: "Google LLC", country: "United States", ... }
```
```

--------------------------------

### Plus API Lookup

Source: https://github.com/ipinfo/node/blob/master/README.md

Demonstrates how to use the IPinfo Plus API to retrieve enhanced IP data, including mobile carrier and privacy information. Authentication with a token is required.

```APIDOC
## Plus API Lookup

### Description
This endpoint allows you to retrieve enhanced IP data, including mobile carrier information and privacy detection, using the Plus API. Authentication with your token is required.

### Method
`POST` (Implicit, as it's a library function call)

### Endpoint
N/A (Library function)

### Parameters
- `ipinfoWrapper`: An instance of `IPinfoPlusWrapper` initialized with your API token.
- `ip`: The IP address to look up (e.g., "8.8.8.8").

### Request Example
```typescript
import { IPinfoPlusWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoPlusWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.ip);
console.log(ipinfo.geo);
console.log(ipinfo.mobile);
console.log(ipinfo.anonymous);
```

### Response
#### Success Response
Returns an object containing detailed IP information, including `ip`, `geo`, `mobile`, and `anonymous` data.

#### Response Example
```json
{
  "ip": "8.8.8.8",
  "geo": {
    "city": "Mountain View",
    "region": "California",
    "regionCode": "CA",
    "country": "United States",
    "countryCode": "US",
    "..."
  },
  "mobile": {
    "carrier": "...",
    "mcc": "...",
    "mnc": "..."
  },
  "anonymous": {
    "isProxy": false,
    "isRelay": false,
    "isTor": false,
    "..."
  }
}
```
```

--------------------------------

### Configure Custom LRU Cache

Source: https://github.com/ipinfo/node/blob/master/README.md

Implement a custom caching strategy using the LruCache interface. Default cache settings are 1 day TTL and 5000 items.

```javascript
const { IPinfoWrapper, LruCache } = require("node-ipinfo");

const cacheOptions = {
    max: 5000,
    ttl: 24 * 1000 * 60 * 60
};

const cache = new LruCache(cacheOptions);

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", cache);
```

--------------------------------

### Perform Batch IP Lookups

Source: https://github.com/ipinfo/node/blob/master/README.md

Efficiently retrieve details for multiple IP addresses by sending them in a single batch request. The library handles chunking operations automatically.

```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");

const ips = ["1.1.1.1", "8.8.8.8", "1.2.3.4/country"];

ipinfoWrapper
    .getBatch(ips)
    .then(batch => console.log(batch));
```

--------------------------------

### IPinfoLiteWrapper: Lookup IP Address (Lite API)

Source: https://context7.com/ipinfo/node/llms.txt

Use IPinfoLiteWrapper for basic geolocation and ASN fields from the free Lite API. Pass an IP address or omit for self-lookup. Handles bogon IPs without an HTTP request.

```typescript
import { IPinfoLiteWrapper, IPinfoLite, IPBogon } from "node-ipinfo";

const ipinfo = new IPinfoLiteWrapper(process.env.IPINFO_TOKEN!); 

// Named IP
const data = (await ipinfo.lookupIp("8.8.8.8")) as IPinfoLite;
console.log(data.ip);            // "8.8.8.8"
console.log(data.asn);           // "AS15169"
console.log(data.asName);        // "Google LLC"
console.log(data.asDomain);      // "google.com"
console.log(data.countryCode);   // "US"
console.log(data.country);       // "United States"
console.log(data.continentCode); // "NA"
console.log(data.continent);     // "North America"
console.log(data.isEU);          // false

// Resolve caller's own IP (omit argument or pass undefined)
const me = (await ipinfo.lookupIp()) as IPinfoLite;
console.log(me.countryCode); // e.g. "DE"

// Bogon short-circuit (no HTTP request)
const bogon = (await ipinfo.lookupIp("10.0.0.1")) as IPBogon;
console.log(bogon.bogon); // true
```

--------------------------------

### Handle lookup errors

Source: https://github.com/ipinfo/node/blob/master/README.md

Demonstrates how to handle potential errors during an IP lookup. It's recommended to catch errors to prevent program crashes and provide fallback values, such as 'N/A' for country codes.

```typescript
const countryCode = ipinfoWrapper
    .lookupIp("1.1.1.1")
    .then((ipinfo) => ipinfo.countryCode)
    .catch((error) => "N/A");
```

--------------------------------

### Batch IP Lookups

Source: https://github.com/ipinfo/node/blob/master/README.md

Perform batch lookups for multiple IP addresses to improve efficiency. The library handles chunking operations behind the scenes.

```APIDOC
## Batch Operations

### Description
Retrieves details for multiple IP addresses in a single request, optimizing performance. The library automatically manages the chunking of operations.

### Method
`getBatch(ipAddresses)`

### Parameters
- **ipAddresses** (Array<string>) - An array of IP addresses or IP address with optional filters (e.g., "1.2.3.4/country").

### Response
- (object) - An object containing the batch lookup results.

### Request Example
```typescript
const { IPinfoWrapper } = require("node-ipinfo");

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");

const ips = ["1.1.1.1", "8.8.8.8", "1.2.3.4/country"];

ipinfoWrapper
    .getBatch(ips)
    .then(batch => console.log(batch));
```

### Additional Information
Refer to [the official documentation](https://ipinfo.io/developers/batch) for more details and limitations.
```

--------------------------------

### IPinfoPlusWrapper: Lookup IP Address (Plus API)

Source: https://context7.com/ipinfo/node/llms.txt

Employ IPinfoPlusWrapper for extended data including hostname, detailed geo fields, mobile carrier data, and anonymity signals from the Plus API. Supports self-lookup and provides comprehensive IP insights.

```typescript
import { IPinfoPlusWrapper, IPinfoPlus, IPBogon } from "node-ipinfo";

const ipinfo = new IPinfoPlusWrapper(process.env.IPINFO_TOKEN!);

const data = (await ipinfo.lookupIp("8.8.8.8")) as IPinfoPlus;
console.log(data.ip);       // "8.8.8.8"
console.log(data.hostname); // "dns.google"

console.log(data.geo);
// { 
//   city: "Mountain View", region: "California", region_code: "CA",
//   country: "United States", country_code: "US",
//   latitude: 37.4056, longitude: -122.0775,
//   timezone: "America/Los_Angeles", postal_code: "94043",
//   dma_code: "807", geoname_id: "5375480", radius: 5,
//   country_name: "United States", isEU: false,
//   country_flag_url: "https://cdn.ipinfo.io/static/images/countries-flags/US.svg"
// }

console.log(data.as);
// { asn: "AS15169", name: "Google LLC", domain: "google.com",
//   type: "hosting", last_changed: "2023-01-01" }

console.log(data.mobile);
// { name: undefined, mcc: undefined, mnc: undefined }  (not a mobile IP)

console.log(data.anonymous);
// { is_proxy: false, is_relay: false, is_tor: false, is_vpn: false }

console.log(data.is_anonymous); // false
console.log(data.is_hosting);   // true
```