Merge pull request #33 from IPGeolocation/update/3.0.0

Update v3.0.0 release contents

Author: MudassarTariq

CONTRIBUTING.md

@@ -3,7 +3,7 @@
 This repository contains the public Java SDK package for the IP Geolocation API.
 
 ## Prerequisites
-- Java 21+
+- Java 8+
 - Maven 3.8+
 
 ## Setup
@@ -41,6 +41,12 @@ Live tests consume API credits and are disabled by default.
 IPGEO_RUN_LIVE_TESTS=true IPGEO_FREE_KEY=... IPGEO_PAID_KEY=... mvn -Dtest=IpGeolocationLiveIntegrationTest test
 ```
 
+Optional live hardening tests compare raw API JSON to the typed SDK model and consume additional credits.
+
+```bash
+IPGEO_RUN_LIVE_HARDENING=true IPGEO_PAID_KEY=... mvn -Dtest=IpGeolocationLiveFieldParityTest test
+```
+
 ## Coding and PR Notes
 - Keep changes focused and include tests for behavior changes.
 - Do not commit real API keys, tokens, or secrets.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IPGeolocation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,16 +7,17 @@
   <artifactId>ipgeolocation</artifactId>
   <version>3.0.0</version>
   <name>IPGeolocation Java SDK</name>
-  <description>Enterprise Java SDK for the IP Geolocation API.</description>
+  <description>Java SDK for IP geolocation, company, ASN, VPN and proxy detection, risk signals, timezone, user-agent parsing, and bulk IP intelligence with the IPGeolocation API.</description>
   <url>https://ipgeolocation.io/</url>
   <organization>
     <name>IPGeolocation</name>
     <url>https://ipgeolocation.io/</url>
   </organization>
   <licenses>
     <license>
-      <name>Proprietary</name>
-      <url>https://ipgeolocation.io/tos.html</url>
+      <name>MIT License</name>
+      <url>https://opensource.org/license/mit/</url>
+      <distribution>repo</distribution>
     </license>
   </licenses>
   <developers>
@@ -35,7 +36,7 @@
   </scm>
 
   <properties>
-    <maven.compiler.release>21</maven.compiler.release>
+    <maven.compiler.release>8</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <jackson.version>2.21.1</jackson.version>
     <junit.version>5.11.4</junit.version>
@@ -196,7 +197,7 @@
                   <version>[3.8.0,)</version>
                 </requireMavenVersion>
                 <requireJavaVersion>
-                  <version>[21,)</version>
+                  <version>[1.8,)</version>
                 </requireJavaVersion>
                 <banDuplicatePomDependencyVersions/>
                 <dependencyConvergence/>
@@ -233,6 +234,9 @@
             <version>${maven.javadoc.plugin.version}</version>
             <configuration>
               <source>${maven.compiler.release}</source>
+              <doclint>all,-missing</doclint>
+              <excludePackageNames>io.ipgeolocation.sdk.internal</excludePackageNames>
+              <quiet>true</quiet>
             </configuration>
             <executions>
               <execution>

pom.xml

@@ -3,14 +3,46 @@
 import java.util.Objects;
 
 /**
- * Wraps parsed IP Geolocation API response data with SDK metadata.
+ * Wraps parsed IPGeolocation API response data with SDK metadata.
  *
  * @param <T> parsed response body type
- * @param data parsed response payload; may be {@code null} for empty API responses
- * @param metadata response metadata extracted from headers and SDK execution metrics
  */
-public record ApiResponse<T>(T data, ApiResponseMetadata metadata) {
-  public ApiResponse {
-    Objects.requireNonNull(metadata, "metadata must not be null");
+public final class ApiResponse<T> {
+  private final T data;
+  private final ApiResponseMetadata metadata;
+
+  public ApiResponse(T data, ApiResponseMetadata metadata) {
+    this.data = data;
+    this.metadata = Objects.requireNonNull(metadata, "metadata must not be null");
+  }
+
+  public T data() {
+    return data;
+  }
+
+  public ApiResponseMetadata metadata() {
+    return metadata;
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    if (this == other) {
+      return true;
+    }
+    if (!(other instanceof ApiResponse)) {
+      return false;
+    }
+    ApiResponse<?> that = (ApiResponse<?>) other;
+    return Objects.equals(data, that.data) && Objects.equals(metadata, that.metadata);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(data, metadata);
+  }
+
+  @Override
+  public String toString() {
+    return "ApiResponse{data=" + data + ", metadata=" + metadata + '}';
   }
 }

src/main/java/io/ipgeolocation/sdk/ApiResponse.java

@@ -1,36 +1,60 @@
 package io.ipgeolocation.sdk;
 
+import io.ipgeolocation.sdk.internal.Compat;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 /**
- * Metadata extracted from IP Geolocation API response headers and SDK execution.
- *
- * @param creditsCharged parsed value of {@code X-Credits-Charged}, or {@code null} when missing
- *     or non-numeric
- * @param successfulRecords parsed value of {@code X-Successful-Record}, or {@code null} when
- *     missing or non-numeric
- * @param statusCode HTTP status code of the final response
- * @param durationMs total request duration in milliseconds
- * @param rawHeaders immutable response header map with original header names
+ * Metadata extracted from IPGeolocation API response headers and SDK execution.
  */
-public record ApiResponseMetadata(
-    Integer creditsCharged,
-    Integer successfulRecords,
-    int statusCode,
-    long durationMs,
-    Map<String, List<String>> rawHeaders) {
+public final class ApiResponseMetadata {
+  private final Integer creditsCharged;
+  private final Integer successfulRecords;
+  private final int statusCode;
+  private final long durationMs;
+  private final Map<String, List<String>> rawHeaders;
 
-  public ApiResponseMetadata {
+  public ApiResponseMetadata(
+      Integer creditsCharged,
+      Integer successfulRecords,
+      int statusCode,
+      long durationMs,
+      Map<String, List<String>> rawHeaders) {
     if (statusCode < 100 || statusCode > 599) {
       throw new IllegalArgumentException("statusCode must be between 100 and 599");
     }
     if (durationMs < 0) {
       throw new IllegalArgumentException("durationMs must be >= 0");
     }
-    rawHeaders = normalizeHeaders(rawHeaders);
+    this.creditsCharged = creditsCharged;
+    this.successfulRecords = successfulRecords;
+    this.statusCode = statusCode;
+    this.durationMs = durationMs;
+    this.rawHeaders = normalizeHeaders(rawHeaders);
+  }
+
+  public Integer creditsCharged() {
+    return creditsCharged;
+  }
+
+  public Integer successfulRecords() {
+    return successfulRecords;
+  }
+
+  public int statusCode() {
+    return statusCode;
+  }
+
+  public long durationMs() {
+    return durationMs;
+  }
+
+  public Map<String, List<String>> rawHeaders() {
+    return rawHeaders;
   }
 
   /**
@@ -41,7 +65,7 @@ public record ApiResponseMetadata(
    * @throws IllegalArgumentException when name is null or blank
    */
   public List<String> headerValues(String name) {
-    if (name == null || name.isBlank()) {
+    if (Compat.isBlank(name)) {
       throw new IllegalArgumentException("header name must not be blank");
     }
     for (Map.Entry<String, List<String>> entry : rawHeaders.entrySet()) {
@@ -50,7 +74,7 @@ public List<String> headerValues(String name) {
         return entry.getValue();
       }
     }
-    return List.of();
+    return Collections.emptyList();
   }
 
   /**
@@ -67,19 +91,60 @@ public String firstHeaderValue(String name) {
 
   private static Map<String, List<String>> normalizeHeaders(Map<String, List<String>> headers) {
     if (headers == null || headers.isEmpty()) {
-      return Map.of();
+      return Collections.emptyMap();
     }
     Map<String, List<String>> normalized = new LinkedHashMap<>(headers.size());
-    headers.forEach(
-        (name, values) -> {
-          if (name == null) {
-            return;
-          }
-          normalized.put(name, values == null || values.isEmpty() ? List.of() : List.copyOf(values));
-        });
+    for (Map.Entry<String, List<String>> entry : headers.entrySet()) {
+      String name = entry.getKey();
+      List<String> values = entry.getValue();
+      if (name == null) {
+        continue;
+      }
+      normalized.put(
+          name,
+          values == null || values.isEmpty()
+              ? Collections.<String>emptyList()
+              : Collections.unmodifiableList(new ArrayList<String>(values)));
+    }
     if (normalized.isEmpty()) {
-      return Map.of();
+      return Collections.emptyMap();
     }
     return Collections.unmodifiableMap(normalized);
   }
+
+  @Override
+  public boolean equals(Object other) {
+    if (this == other) {
+      return true;
+    }
+    if (!(other instanceof ApiResponseMetadata)) {
+      return false;
+    }
+    ApiResponseMetadata that = (ApiResponseMetadata) other;
+    return statusCode == that.statusCode
+        && durationMs == that.durationMs
+        && Objects.equals(creditsCharged, that.creditsCharged)
+        && Objects.equals(successfulRecords, that.successfulRecords)
+        && Objects.equals(rawHeaders, that.rawHeaders);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(creditsCharged, successfulRecords, statusCode, durationMs, rawHeaders);
+  }
+
+  @Override
+  public String toString() {
+    return "ApiResponseMetadata{creditsCharged="
+        + creditsCharged
+        + ", successfulRecords="
+        + successfulRecords
+        + ", statusCode="
+        + statusCode
+        + ", durationMs="
+        + durationMs
+        + ", rawHeaders="
+        + rawHeaders
+        + '}';
+  }
 }

src/main/java/io/ipgeolocation/sdk/ApiResponseMetadata.java

@@ -1,6 +1,7 @@
 package io.ipgeolocation.sdk;
 
 import io.ipgeolocation.sdk.exceptions.ValidationException;
+import io.ipgeolocation.sdk.internal.Compat;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -9,7 +10,7 @@
  * Request payload and query parameters for the Unified IPGeolocation API bulk-lookup endpoint
  * {@code POST /v3/ipgeo-bulk}.
  *
- * <p>Use this type with the IP Geolocation API at https://ipgeolocation.io.
+ * <p>Use this type with the IPGeolocation API at https://ipgeolocation.io.
  *
  * <p>Use {@link Builder} to construct instances. Query values for {@code include},
  * {@code fields}, and {@code excludes} are passed through as provided and validated by the API.
@@ -25,11 +26,11 @@ public final class BulkLookupIpGeolocationRequest {
   private final ResponseFormat output;
 
   private BulkLookupIpGeolocationRequest(Builder builder) {
-    this.ips = List.copyOf(builder.ips);
+    this.ips = Compat.immutableList(builder.ips);
     this.lang = builder.lang;
-    this.include = List.copyOf(builder.include);
-    this.fields = List.copyOf(builder.fields);
-    this.excludes = List.copyOf(builder.excludes);
+    this.include = Compat.immutableList(builder.include);
+    this.fields = Compat.immutableList(builder.fields);
+    this.excludes = Compat.immutableList(builder.excludes);
     this.userAgent = builder.userAgent;
     this.output = builder.output;
   }
@@ -195,7 +196,7 @@ public Builder userAgent(String userAgent) {
         this.userAgent = null;
         return this;
       }
-      if (userAgent.isBlank()) {
+      if (Compat.isBlank(userAgent)) {
         throw new ValidationException("userAgent must not be blank");
       }
       this.userAgent = userAgent;
@@ -233,7 +234,7 @@ public BulkLookupIpGeolocationRequest build() {
     }
 
     private static String requireToken(String value, String field) {
-      if (value == null || value.isBlank()) {
+      if (Compat.isBlank(value)) {
         throw new ValidationException(field + " value must not be blank");
       }
       return value;