masklen

Official JavaScript/TypeScript SDK for the masklen.dev IP intelligence API.

Zero external dependencies. Works in Node.js 18+ and modern browsers.

Installation

npm install masklen

Quick start

import { MasklenClient } from "masklen";

const client = new MasklenClient({ apiKey: "your-api-key" });

// Look up your own IP
const self = await client.lookupSelf();
console.log(self.ip, self.location?.country);

// Look up a specific IP
const result = await client.lookup("8.8.8.8");
console.log(result.location?.city);

// Look up multiple IPs at once
const batch = await client.lookupBatch(["8.8.8.8", "1.1.1.1"]);
for (const item of batch.results) {
  if ("error" in item) {
    console.error(item.ip, item.error.message);
  } else {
    console.log(item.ip, item.location?.country);
  }
}

Constructor

new MasklenClient(options: MasklenClientOptions)

| Option | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------- | | apiKey | string | Yes | Your masklen.dev API key | | baseUrl | string | No | Override the base URL (default: https://masklen.dev) |

Methods

lookupSelf(opts?)

Look up the caller's own IP address.

client.lookupSelf(opts?: { fields?: Field[] }): Promise<LookupResult>

lookup(ip, opts?)

Look up a specific IPv4 or IPv6 address.

client.lookup(ip: string, opts?: { fields?: Field[] }): Promise<LookupResult>

lookupBatch(ips, opts?)

Look up up to 1000 IP addresses in a single request.

client.lookupBatch(ips: string[], opts?: { fields?: Field[] }): Promise<BatchResult>

Fields filtering

Pass a fields array to request only the data you need. Available fields: "location", "network", "privacy", "locale".

const result = await client.lookup("8.8.8.8", {
  fields: ["location", "privacy"],
});

console.log(result.location?.country);
console.log(result.privacy?.vpn);

Error handling

Non-2xx responses throw a MasklenError with code, status, and message properties.

import { MasklenClient, MasklenError } from "masklen";

const client = new MasklenClient({ apiKey: "your-api-key" });

try {
  const result = await client.lookup("not-an-ip");
} catch (err) {
  if (err instanceof MasklenError) {
    console.error(`API error ${err.status}: [${err.code}] ${err.message}`);
  } else {
    throw err;
  }
}

Response types

interface LookupResult {
  ip: string;
  location?: Location;
  network?: Network;
  privacy?: Privacy;
  locale?: Locale;
}

interface Location {
  city: string | null;
  region: string | null;
  country: string | null;
  country_code: string | null;
  latitude: number | null;
  longitude: number | null;
  postal_code: string | null;
  timezone: string | null;
}

interface Network {
  asn: string | null;
  isp: string | null;
  organization: string | null;
  domain: string | null;
}

interface Privacy {
  vpn: boolean;
  proxy: boolean;
  tor: boolean;
  hosting: boolean;
  threat_level: "low" | "medium";
}

interface Locale {
  currency: string | null;
  currency_symbol: string | null;
  calling_code: string | null;
  languages: string[];
  flag: string | null;
}

interface BatchResult {
  results: Array<LookupResult | BatchItemError>;
}

interface BatchItemError {
  ip: string;
  error: {
    code: string;
    message: string;
  };
}

License

MIT