csv2geo-sdk 1.1.0 → 1.2.0

package/README.md

@@ -51,7 +51,7 @@ if (result) {
 const { Client } = require('csv2geo-sdk');
 
 const client = new Client('your_api_key', {
-  baseUrl: 'https://api.csv2geo.com/v1',  // optional
+  baseUrl: 'https://csv2geo.com/api/v1',  // optional
   timeout: 30000,  // optional, milliseconds
   autoRetry: true,  // optional, retry on rate limit
 });
@@ -203,6 +203,11 @@ Sign up at [csv2geo.com](https://csv2geo.com) to get your API key.
 - [API Documentation](https://acenji.github.io/csv2geo-api/docs/)
 - [OpenAPI Specification](https://github.com/acenji/csv2geo-api/blob/main/openapi.yaml)
 
+## Community & Support
+
+- **Questions & feature requests:** [GitHub Discussions](https://github.com/acenji/csv2geo-api/discussions)
+- **Bug reports:** [GitHub Issues](https://github.com/acenji/csv2geo-api/issues)
+
 ## License
 
 MIT License - see [LICENSE](https://github.com/acenji/csv2geo-api/blob/main/LICENSE) for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "csv2geo-sdk",
-  "version": "1.1.0",
-  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 39 countries, 42 endpoints. Forward, reverse, batch, places, divisions (incl. postcode → boundary), coverage, autocomplete. 3,000 free requests/day.",
+  "version": "1.2.0",
+  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 39 countries, 42+ endpoints. Forward, reverse, batch, places, divisions (incl. postcode → boundary), IP geolocation with county overlay, coverage, autocomplete. 3,000 free requests/day.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "files": [

package/src/index.d.ts

@@ -3,7 +3,7 @@
  */
 
 export interface ClientOptions {
-  /** API base URL (default: https://api.csv2geo.com/v1) */
+  /** API base URL (default: https://csv2geo.com/api/v1) */
   baseUrl?: string;
   /** Request timeout in milliseconds (default: 30000) */
   timeout?: number;
@@ -105,6 +105,44 @@ export class Client {
    * @returns Array of responses
    */
   reverseBatch(coordinates: Coordinate[]): Promise<GeocodeResponse[]>;
+
+  /**
+   * IP geolocation. Returns country/region/city/postcode/location/timezone/ISP,
+   * plus county + locality + confidence for residential IPs (Sprint 2.7).
+   * @param ip IPv4 or IPv6 string
+   */
+  ip(ip: string): Promise<IPGeoResponse>;
+
+  /**
+   * Like {@link ip}, but uses the requester's IP.
+   */
+  ipMe(): Promise<IPGeoResponse>;
+
+  /**
+   * Batch IP lookup. Up to 1000 IPs per call.
+   */
+  ipBatch(ips: string[]): Promise<{ results: IPGeoResponse[] }>;
+}
+
+export interface IPGeoResponse {
+  ip: string;
+  country?: { code: string; name?: string; wikidata?: string };
+  region?: { code?: string; name?: string };
+  city?: { name: string };
+  postcode?: string;
+  location?: {
+    latitude: number;
+    longitude: number;
+    accuracy_radius_km: number;
+  };
+  timezone?: string;
+  isp?: { asn?: number; name?: string };
+  county?: { name: string; subtype?: string; wikidata?: string };
+  locality?: { name: string; subtype?: string; wikidata?: string };
+  confidence?: 'high' | 'medium' | 'low';
+  accuracy_disclaimer?: string;
+  source: string;
+  db_build_at?: string;
 }
 
 export class CSV2GEOError extends Error {

package/src/index.js

@@ -20,7 +20,7 @@ const {
   APIError,
 } = require('./errors');
 
-const DEFAULT_BASE_URL = 'https://api.csv2geo.com/v1';
+const DEFAULT_BASE_URL = 'https://csv2geo.com/api/v1';
 const DEFAULT_TIMEOUT = 30000;
 const MAX_RETRIES = 3;
 
@@ -75,7 +75,7 @@ class Client {
         headers: {
           'Authorization': `Bearer ${this.apiKey}`,
           'Content-Type': 'application/json',
-          'User-Agent': 'csv2geo-node/1.0.0',
+          'User-Agent': 'csv2geo-node/1.2.0',
         },
         signal: controller.signal,
       };
@@ -563,6 +563,56 @@ class Client {
       },
     };
   }
+
+  // ─────────────────────────────────────────────────────────
+  // IP geolocation (Sprint 2.7)
+  //
+  // MaxMind GeoLite2 .mmdb lookup with our county overlay.
+  // Bundled into every plan (including Free); no separate billing.
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * IP → geolocation. Returns country, region, city, postcode, location,
+   * timezone, ISP, and (for residential IPs) county + locality + confidence.
+   *
+   * @param {string} ip - IPv4 or IPv6 address (e.g. "8.8.8.8")
+   * @returns {Promise<Object>} canonical /v1/ip response shape
+   * @example
+   *   const r = await client.ip('8.8.8.8');
+   *   console.log(r.country.code, r.county?.name, r.confidence);
+   */
+  async ip(ip) {
+    if (!ip || typeof ip !== 'string') {
+      throw new InvalidRequestError('ip must be a non-empty string');
+    }
+    return this._request('GET', '/ip', { ip });
+  }
+
+  /**
+   * Like {@link ip}, but uses the requester's IP (the one Laravel sees).
+   * Useful from browser/server contexts where you want "where is the caller".
+   *
+   * @returns {Promise<Object>} canonical /v1/ip response shape
+   */
+  async ipMe() {
+    return this._request('GET', '/ip/me');
+  }
+
+  /**
+   * Batch IP lookup. Up to 1000 IPs per call.
+   *
+   * @param {string[]} ips - array of IPs
+   * @returns {Promise<{results: Object[]}>}
+   */
+  async ipBatch(ips) {
+    if (!Array.isArray(ips) || ips.length === 0) {
+      throw new InvalidRequestError('ips must be a non-empty array');
+    }
+    if (ips.length > 1000) {
+      throw new InvalidRequestError('ipBatch supports at most 1000 IPs per call');
+    }
+    return this._request('POST', '/ip/batch', {}, { ips });
+  }
 }
 
 module.exports = {