ip-finder-client 1.0.0

package/README.md

@@ -0,0 +1,209 @@
+# ip-finder-client
+
+A lightweight, zero-dependency Node.js client for the IP Finder API. Get IP geolocation, ASN information, and network details with ease.
+
+## Installation
+
+```bash
+npm install ip-finder-client
+```
+
+```bash
+yarn add ip-finder-client
+```
+
+```bash
+pnpm add ip-finder-client
+```
+
+## Quick Start
+
+```typescript
+import { IPFinder } from 'ip-finder-client';
+
+const client = new IPFinder({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.your-domain.com' // Your API endpoint
+});
+
+// Look up an IP address
+const result = await client.lookup('8.8.8.8');
+
+console.log(result.geo?.country);      // "United States"
+console.log(result.geo?.city);         // "Mountain View"
+console.log(result.asn?.organization); // "Google LLC"
+```
+
+## Configuration
+
+```typescript
+const client = new IPFinder({
+  // Required: Your API key
+  apiKey: 'your-api-key',
+
+  // Optional: API base URL (defaults to production)
+  baseUrl: 'https://api.your-domain.com',
+
+  // Optional: Request timeout in ms (default: 10000)
+  timeout: 5000,
+
+  // Optional: Number of retries for failed requests (default: 2)
+  retries: 3,
+});
+```
+
+## API Reference
+
+### `lookup(ip: string): Promise<IPLookupResult>`
+
+Look up information for a single IP address.
+
+```typescript
+const result = await client.lookup('8.8.8.8');
+
+// Result structure:
+{
+  ip: '8.8.8.8',
+  geo: {
+    city: 'Mountain View',
+    region: 'California',
+    regionCode: 'CA',
+    country: 'United States',
+    countryCode: 'US',
+    continent: 'North America',
+    continentCode: 'NA',
+    latitude: 37.4056,
+    longitude: -122.0775,
+    timezone: 'America/Los_Angeles',
+    postalCode: '94043'
+  },
+  asn: {
+    asn: 15169,
+    organization: 'Google LLC',
+    isp: 'Google LLC'
+  },
+  network: {
+    cidr: '8.8.8.0/24',
+    startIp: '8.8.8.0',
+    endIp: '8.8.8.255',
+    type: 'assigned',
+    registry: 'arin'
+  },
+  version: 4
+}
+```
+
+### `lookupBatch(ips: string[]): Promise<(IPLookupResult | IPFinderError)[]>`
+
+Look up multiple IP addresses in parallel.
+
+```typescript
+const results = await client.lookupBatch(['8.8.8.8', '1.1.1.1', '9.9.9.9']);
+
+results.forEach(result => {
+  if (result instanceof IPFinderError) {
+    console.error(`Error: ${result.message}`);
+  } else {
+    console.log(`${result.ip}: ${result.geo?.country}`);
+  }
+});
+```
+
+### `healthCheck(): Promise<boolean>`
+
+Check if the API is healthy and reachable.
+
+```typescript
+const isHealthy = await client.healthCheck();
+console.log(isHealthy ? 'API is up!' : 'API is down');
+```
+
+### Rate Limiting
+
+Rate limit information is available after each request:
+
+```typescript
+await client.lookup('8.8.8.8');
+
+console.log(client.rateLimit);
+// { limit: 1000, remaining: 999, reset: 1703980800 }
+```
+
+## Error Handling
+
+```typescript
+import { IPFinder, IPFinderError } from 'ip-finder-client';
+
+try {
+  const result = await client.lookup('invalid-ip');
+} catch (error) {
+  if (error instanceof IPFinderError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status Code: ${error.statusCode}`);
+    console.error(`Error Code: ${error.code}`);
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `TIMEOUT` | Request timed out |
+| `NETWORK_ERROR` | Network connectivity issue |
+| `BATCH_ERROR` | Error during batch lookup |
+
+### HTTP Status Codes
+
+| Status | Description |
+|--------|-------------|
+| 400 | Invalid IP address format |
+| 401 | Invalid or missing API key |
+| 404 | IP not found in database |
+| 429 | Rate limit exceeded |
+| 500 | Server error |
+
+## CommonJS Usage
+
+```javascript
+const { IPFinder } = require('ip-finder-client');
+
+const client = new IPFinder({ apiKey: 'your-api-key' });
+```
+
+## Factory Function
+
+Alternatively, use the factory function:
+
+```typescript
+import { createClient } from 'ip-finder-client';
+
+const client = createClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.your-domain.com'
+});
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  IPFinderConfig,
+  IPLookupResult,
+  GeoLocation,
+  ASNInfo,
+  NetworkInfo,
+  RateLimitInfo
+} from 'ip-finder-client';
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import type { IPFinderConfig, IPLookupResult, APIError, RateLimitInfo, GeoLocation, ASNInfo, NetworkInfo } from './types';
+export type { IPFinderConfig, IPLookupResult, APIError, RateLimitInfo, GeoLocation, ASNInfo, NetworkInfo, };
+/**
+ * Custom error class for IP Finder API errors
+ */
+export declare class IPFinderError extends Error {
+    readonly statusCode: number;
+    readonly code?: string;
+    constructor(message: string, statusCode: number, code?: string);
+}
+/**
+ * IP Finder client for looking up IP address information
+ *
+ * @example
+ * ```ts
+ * import { IPFinder } from 'ip-finder-client';
+ *
+ * const client = new IPFinder({ apiKey: 'your-api-key' });
+ * const result = await client.lookup('8.8.8.8');
+ * console.log(result.geo?.country); // "United States"
+ * ```
+ */
+export declare class IPFinder {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    /** Rate limit info from the last request */
+    rateLimit?: RateLimitInfo;
+    constructor(config: IPFinderConfig);
+    /**
+     * Look up information for an IP address
+     *
+     * @param ip - IPv4 or IPv6 address to look up
+     * @returns IP lookup result with geo, ASN, and network information
+     * @throws {IPFinderError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const result = await client.lookup('8.8.8.8');
+     * console.log(result.geo?.city); // "Mountain View"
+     * console.log(result.asn?.organization); // "Google LLC"
+     * ```
+     */
+    lookup(ip: string): Promise<IPLookupResult>;
+    /**
+     * Look up the current request's IP address (useful for "what's my IP" functionality)
+     * Note: This requires your API to support a special endpoint for this
+     *
+     * @returns IP lookup result for the requesting IP
+     */
+    lookupSelf(): Promise<IPLookupResult>;
+    /**
+     * Batch lookup multiple IP addresses
+     *
+     * @param ips - Array of IP addresses to look up
+     * @returns Array of lookup results (or errors for failed lookups)
+     *
+     * @example
+     * ```ts
+     * const results = await client.lookupBatch(['8.8.8.8', '1.1.1.1']);
+     * results.forEach(r => console.log(r.ip, r.geo?.country));
+     * ```
+     */
+    lookupBatch(ips: string[]): Promise<(IPLookupResult | IPFinderError)[]>;
+    /**
+     * Check if the API is healthy and reachable
+     *
+     * @returns true if the API is healthy
+     */
+    healthCheck(): Promise<boolean>;
+    private fetch;
+    private parseRateLimitHeaders;
+    private sleep;
+}
+/**
+ * Create a new IP Finder client instance
+ *
+ * @param config - Client configuration
+ * @returns New IPFinder instance
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'ip-finder-client';
+ *
+ * const client = createClient({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://api.example.com'
+ * });
+ *
+ * const result = await client.lookup('8.8.8.8');
+ * ```
+ */
+export declare function createClient(config: IPFinderConfig): IPFinder;
+export default IPFinder;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,QAAQ,EACR,aAAa,EACb,WAAW,EACX,OAAO,EACP,WAAW,EACZ,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,cAAc,EACd,cAAc,EACd,QAAQ,EACR,aAAa,EACb,WAAW,EACX,OAAO,EACP,WAAW,GACZ,CAAC;AAMF;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAO/D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,4CAA4C;IACrC,SAAS,CAAC,EAAE,aAAa,CAAC;gBAErB,MAAM,EAAE,cAAc;IAWlC;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA+BjD;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;IAO3C;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,cAAc,GAAG,aAAa,CAAC,EAAE,CAAC;IAqB7E;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;YAgBvB,KAAK;IAuDnB,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,KAAK;CAGd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAE7D;AAGD,eAAe,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,223 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  IPFinder: () => IPFinder,
+  IPFinderError: () => IPFinderError,
+  createClient: () => createClient,
+  default: () => src_default
+});
+module.exports = __toCommonJS(src_exports);
+var DEFAULT_BASE_URL = "https://your-api-domain.com";
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_RETRIES = 2;
+var IPFinderError = class _IPFinderError extends Error {
+  statusCode;
+  code;
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "IPFinderError";
+    this.statusCode = statusCode;
+    this.code = code;
+    Object.setPrototypeOf(this, _IPFinderError.prototype);
+  }
+};
+var IPFinder = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  retries;
+  /** Rate limit info from the last request */
+  rateLimit;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+  }
+  /**
+   * Look up information for an IP address
+   *
+   * @param ip - IPv4 or IPv6 address to look up
+   * @returns IP lookup result with geo, ASN, and network information
+   * @throws {IPFinderError} When the API returns an error
+   *
+   * @example
+   * ```ts
+   * const result = await client.lookup('8.8.8.8');
+   * console.log(result.geo?.city); // "Mountain View"
+   * console.log(result.asn?.organization); // "Google LLC"
+   * ```
+   */
+  async lookup(ip) {
+    if (!ip || typeof ip !== "string") {
+      throw new Error("IP address is required and must be a string");
+    }
+    const url = `${this.baseUrl}/v1/ip/${encodeURIComponent(ip.trim())}`;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const response = await this.fetch(url);
+        return response;
+      } catch (err) {
+        lastError = err;
+        if (err instanceof IPFinderError && err.statusCode >= 400 && err.statusCode < 500) {
+          throw err;
+        }
+        if (attempt < this.retries) {
+          await this.sleep(Math.pow(2, attempt) * 100);
+        }
+      }
+    }
+    throw lastError || new Error("Request failed");
+  }
+  /**
+   * Look up the current request's IP address (useful for "what's my IP" functionality)
+   * Note: This requires your API to support a special endpoint for this
+   *
+   * @returns IP lookup result for the requesting IP
+   */
+  async lookupSelf() {
+    const url = `${this.baseUrl}/v1/ip/me`;
+    const response = await this.fetch(url);
+    return response;
+  }
+  /**
+   * Batch lookup multiple IP addresses
+   *
+   * @param ips - Array of IP addresses to look up
+   * @returns Array of lookup results (or errors for failed lookups)
+   *
+   * @example
+   * ```ts
+   * const results = await client.lookupBatch(['8.8.8.8', '1.1.1.1']);
+   * results.forEach(r => console.log(r.ip, r.geo?.country));
+   * ```
+   */
+  async lookupBatch(ips) {
+    const results = await Promise.allSettled(
+      ips.map((ip) => this.lookup(ip))
+    );
+    return results.map((result, index) => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      const err = result.reason;
+      if (err instanceof IPFinderError) {
+        return err;
+      }
+      return new IPFinderError(
+        err?.message || "Unknown error",
+        0,
+        "BATCH_ERROR"
+      );
+    });
+  }
+  /**
+   * Check if the API is healthy and reachable
+   *
+   * @returns true if the API is healthy
+   */
+  async healthCheck() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const response = await fetch(`${this.baseUrl}/healthz`, {
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  async fetch(url) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "X-API-Key": this.apiKey,
+          "Accept": "application/json",
+          "User-Agent": "ip-finder-client/1.0.0"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      this.parseRateLimitHeaders(response.headers);
+      if (!response.ok) {
+        let errorBody = null;
+        try {
+          errorBody = await response.json();
+        } catch {
+        }
+        throw new IPFinderError(
+          errorBody?.error || `HTTP ${response.status}`,
+          response.status,
+          errorBody?.code
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof IPFinderError) {
+        throw err;
+      }
+      if (err instanceof Error) {
+        if (err.name === "AbortError") {
+          throw new IPFinderError("Request timeout", 408, "TIMEOUT");
+        }
+        throw new IPFinderError(err.message, 0, "NETWORK_ERROR");
+      }
+      throw new IPFinderError("Unknown error", 0, "UNKNOWN");
+    }
+  }
+  parseRateLimitHeaders(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      this.rateLimit = {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10)
+      };
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createClient(config) {
+  return new IPFinder(config);
+}
+var src_default = IPFinder;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IPFinder,
+  IPFinderError,
+  createClient
+});

package/dist/index.mjs

@@ -0,0 +1,196 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://your-api-domain.com";
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_RETRIES = 2;
+var IPFinderError = class _IPFinderError extends Error {
+  statusCode;
+  code;
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "IPFinderError";
+    this.statusCode = statusCode;
+    this.code = code;
+    Object.setPrototypeOf(this, _IPFinderError.prototype);
+  }
+};
+var IPFinder = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  retries;
+  /** Rate limit info from the last request */
+  rateLimit;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+  }
+  /**
+   * Look up information for an IP address
+   *
+   * @param ip - IPv4 or IPv6 address to look up
+   * @returns IP lookup result with geo, ASN, and network information
+   * @throws {IPFinderError} When the API returns an error
+   *
+   * @example
+   * ```ts
+   * const result = await client.lookup('8.8.8.8');
+   * console.log(result.geo?.city); // "Mountain View"
+   * console.log(result.asn?.organization); // "Google LLC"
+   * ```
+   */
+  async lookup(ip) {
+    if (!ip || typeof ip !== "string") {
+      throw new Error("IP address is required and must be a string");
+    }
+    const url = `${this.baseUrl}/v1/ip/${encodeURIComponent(ip.trim())}`;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const response = await this.fetch(url);
+        return response;
+      } catch (err) {
+        lastError = err;
+        if (err instanceof IPFinderError && err.statusCode >= 400 && err.statusCode < 500) {
+          throw err;
+        }
+        if (attempt < this.retries) {
+          await this.sleep(Math.pow(2, attempt) * 100);
+        }
+      }
+    }
+    throw lastError || new Error("Request failed");
+  }
+  /**
+   * Look up the current request's IP address (useful for "what's my IP" functionality)
+   * Note: This requires your API to support a special endpoint for this
+   *
+   * @returns IP lookup result for the requesting IP
+   */
+  async lookupSelf() {
+    const url = `${this.baseUrl}/v1/ip/me`;
+    const response = await this.fetch(url);
+    return response;
+  }
+  /**
+   * Batch lookup multiple IP addresses
+   *
+   * @param ips - Array of IP addresses to look up
+   * @returns Array of lookup results (or errors for failed lookups)
+   *
+   * @example
+   * ```ts
+   * const results = await client.lookupBatch(['8.8.8.8', '1.1.1.1']);
+   * results.forEach(r => console.log(r.ip, r.geo?.country));
+   * ```
+   */
+  async lookupBatch(ips) {
+    const results = await Promise.allSettled(
+      ips.map((ip) => this.lookup(ip))
+    );
+    return results.map((result, index) => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      const err = result.reason;
+      if (err instanceof IPFinderError) {
+        return err;
+      }
+      return new IPFinderError(
+        err?.message || "Unknown error",
+        0,
+        "BATCH_ERROR"
+      );
+    });
+  }
+  /**
+   * Check if the API is healthy and reachable
+   *
+   * @returns true if the API is healthy
+   */
+  async healthCheck() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const response = await fetch(`${this.baseUrl}/healthz`, {
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  async fetch(url) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "X-API-Key": this.apiKey,
+          "Accept": "application/json",
+          "User-Agent": "ip-finder-client/1.0.0"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      this.parseRateLimitHeaders(response.headers);
+      if (!response.ok) {
+        let errorBody = null;
+        try {
+          errorBody = await response.json();
+        } catch {
+        }
+        throw new IPFinderError(
+          errorBody?.error || `HTTP ${response.status}`,
+          response.status,
+          errorBody?.code
+        );
+      }
+      const data = await response.json();
+      return data;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof IPFinderError) {
+        throw err;
+      }
+      if (err instanceof Error) {
+        if (err.name === "AbortError") {
+          throw new IPFinderError("Request timeout", 408, "TIMEOUT");
+        }
+        throw new IPFinderError(err.message, 0, "NETWORK_ERROR");
+      }
+      throw new IPFinderError("Unknown error", 0, "UNKNOWN");
+    }
+  }
+  parseRateLimitHeaders(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      this.rateLimit = {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10)
+      };
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createClient(config) {
+  return new IPFinder(config);
+}
+var src_default = IPFinder;
+export {
+  IPFinder,
+  IPFinderError,
+  createClient,
+  src_default as default
+};

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Configuration options for the IP Finder client
+ */
+export interface IPFinderConfig {
+    /** Your API key for authentication */
+    apiKey: string;
+    /** Base URL of the IP Finder API (optional, defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 2) */
+    retries?: number;
+}
+/**
+ * Geographic location information
+ */
+export interface GeoLocation {
+    city?: string;
+    region?: string;
+    regionCode?: string;
+    country?: string;
+    countryCode?: string;
+    continent?: string;
+    continentCode?: string;
+    latitude?: number;
+    longitude?: number;
+    timezone?: string;
+    postalCode?: string;
+}
+/**
+ * ASN (Autonomous System Number) information
+ */
+export interface ASNInfo {
+    asn?: number;
+    organization?: string;
+    isp?: string;
+}
+/**
+ * Network allocation information
+ */
+export interface NetworkInfo {
+    cidr?: string;
+    startIp?: string;
+    endIp?: string;
+    type?: string;
+    registry?: string;
+    registryCountry?: string;
+    allocatedDate?: string;
+}
+/**
+ * Complete IP lookup result
+ */
+export interface IPLookupResult {
+    ip: string;
+    geo?: GeoLocation;
+    asn?: ASNInfo;
+    network?: NetworkInfo;
+    isPrivate?: boolean;
+    isReserved?: boolean;
+    version?: 4 | 6;
+}
+/**
+ * Error response from the API
+ */
+export interface APIError {
+    error: string;
+    code?: string;
+    statusCode: number;
+}
+/**
+ * Rate limit information returned in response headers
+ */
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ip-finder-client",
+  "version": "1.0.0",
+  "description": "Lightweight client SDK for IP Finder API - Get IP geolocation, ASN, and network information",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=cjs",
+    "build:esm": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.mjs --format=esm",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "prepublishOnly": "npm run build",
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "ip",
+    "geolocation",
+    "ip-lookup",
+    "geoip",
+    "asn",
+    "whois",
+    "ip-address",
+    "network",
+    "ipv4",
+    "ipv6"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.3.0"
+  }
+}