Release v1.5.13

Make response parsing lenient: never throw because a field is missing or a
different type than expected. The enterprise endpoint can return songs with no
score (also missing isrc/upc/label, and some fields on YouTube-sourced entries).
Those fields are now optional/nullable and degrade instead of raising.

Kept legitimate failures: API status=error, undecodable JSON, transport
errors, and caller-input errors (unknown provider, missing token).

Author: Mikhail Samin's Claude

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>io.audd</groupId>
   <artifactId>audd</artifactId>
-  <version>1.5.12</version>
+  <version>1.5.13</version>
   <packaging>jar</packaging>
 
   <name>AudD Java SDK</name>

src/main/java/io/audd/AsyncAudD.java

@@ -5,6 +5,7 @@
 import io.audd.advanced.AsyncAdvanced;
 import io.audd.customcatalog.AsyncCustomCatalog;
 import io.audd.internal.HttpClient;
+import io.audd.internal.Json;
 import io.audd.internal.ResponseDecoder;
 import io.audd.internal.RetryClass;
 import io.audd.internal.RetryPolicy;
@@ -30,7 +31,7 @@
  * {@link AudD}; safe with try-with-resources.
  */
 public final class AsyncAudD implements AutoCloseable {
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
 
     private final HttpClient http;
     private final HttpClient enterpriseHttp;

src/main/java/io/audd/AudD.java

@@ -6,6 +6,7 @@
 import io.audd.errors.AudDConnectionError;
 import io.audd.internal.HttpClient;
 import io.audd.internal.HttpResponse;
+import io.audd.internal.Json;
 import io.audd.internal.ResponseDecoder;
 import io.audd.internal.RetryClass;
 import io.audd.internal.RetryPolicy;
@@ -49,7 +50,7 @@ public final class AudD implements AutoCloseable {
         + "Get a token at https://dashboard.audd.io and pass it as AudD.builder().apiToken(...) "
         + "or set " + API_TOKEN_ENV_VAR + ".";
 
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
 
     private static final java.util.logging.Logger LOGGER =
             java.util.logging.Logger.getLogger("io.audd");

src/main/java/io/audd/advanced/Advanced.java

@@ -8,6 +8,7 @@
 import io.audd.errors.ErrorMapping;
 import io.audd.internal.HttpClient;
 import io.audd.internal.HttpResponse;
+import io.audd.internal.Json;
 import io.audd.internal.RetryPolicy;
 import io.audd.models.LyricsResult;
 
@@ -25,7 +26,7 @@
  * main client.
  */
 public final class Advanced {
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
 
     private final HttpClient http;
     private final RetryPolicy recognitionPolicy;

src/main/java/io/audd/advanced/AsyncAdvanced.java

@@ -6,6 +6,7 @@
 import io.audd.errors.AudDSerializationError;
 import io.audd.errors.ErrorMapping;
 import io.audd.internal.HttpClient;
+import io.audd.internal.Json;
 import io.audd.internal.RetryPolicy;
 import io.audd.models.LyricsResult;
 
@@ -19,7 +20,7 @@
 
 /** Async advanced namespace — mirror of {@link Advanced}. */
 public final class AsyncAdvanced {
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
 
     private final HttpClient http;
     private final RetryPolicy recognitionPolicy;

src/main/java/io/audd/internal/HttpClient.java

@@ -31,7 +31,7 @@ public final class HttpClient implements AutoCloseable {
     public static final long DEFAULT_READ_TIMEOUT_S = 60;
     public static final long ENTERPRISE_READ_TIMEOUT_S = 3600;
 
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
 
     private final AtomicReference<String> apiToken;
     private final OkHttpClient http;

src/main/java/io/audd/internal/Json.java

@@ -0,0 +1,56 @@
+package io.audd.internal;
+
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+/**
+ * Shared, leniently-configured {@link ObjectMapper} for all response parsing.
+ *
+ * <p>A successful API response must never fail to parse because a field is
+ * absent or a different type than expected. The enterprise endpoint, for
+ * example, legitimately returns matches with no {@code score} (and no
+ * {@code isrc}/{@code upc}/{@code label}). The mapper here is configured so
+ * that missing, unknown, and null-for-primitive fields all degrade to
+ * sensible defaults instead of throwing.</p>
+ *
+ * <p>This does not weaken the error contract: a {@code status=error} body is
+ * still turned into a typed exception before any model is decoded, and a body
+ * that is not valid JSON at all still surfaces as a serialization error.</p>
+ */
+public final class Json {
+    private static final ObjectMapper MAPPER = newLenientMapper();
+
+    private Json() {}
+
+    /** The shared lenient mapper. Jackson {@link ObjectMapper} is thread-safe once configured. */
+    public static ObjectMapper mapper() {
+        return MAPPER;
+    }
+
+    /**
+     * Build a mapper that tolerates the natural shape variation of AudD
+     * responses:
+     * <ul>
+     *   <li>unknown keys are ignored (typed models also absorb them via
+     *       {@code @JsonAnySetter}, but this protects any plain POJO too);</li>
+     *   <li>a JSON {@code null} for a primitive field becomes the primitive's
+     *       default rather than throwing;</li>
+     *   <li>a missing {@code @JsonCreator} property is allowed;</li>
+     *   <li>scalars accepted for single-element arrays and vice versa, so a
+     *       field that is sometimes an object and sometimes a list still
+     *       decodes.</li>
+     * </ul>
+     */
+    public static ObjectMapper newLenientMapper() {
+        return new ObjectMapper()
+            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
+            .configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false)
+            .configure(DeserializationFeature.FAIL_ON_MISSING_CREATOR_PROPERTIES, false)
+            .configure(DeserializationFeature.FAIL_ON_NUMBERS_FOR_ENUMS, false)
+            .configure(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL, true)
+            .configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true)
+            .configure(DeserializationFeature.UNWRAP_SINGLE_VALUE_ARRAYS, true)
+            .configure(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT, true)
+            .configure(DeserializationFeature.ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT, true);
+    }
+}

src/main/java/io/audd/internal/UserAgent.java

@@ -2,7 +2,7 @@
 
 /** SDK identifier sent on every request. */
 public final class UserAgent {
-    public static final String SDK_VERSION = "1.5.12";
+    public static final String SDK_VERSION = "1.5.13";
 
     private UserAgent() {}
 

src/main/java/io/audd/models/AppleMusicMetadata.java

@@ -1,9 +1,7 @@
 package io.audd.models;
 
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-@JsonIgnoreProperties(ignoreUnknown = false)
 public final class AppleMusicMetadata extends ForwardCompatible {
     @JsonProperty("artistName") public String artistName;
     @JsonProperty("url") public String url;

src/main/java/io/audd/streams/AsyncStreams.java

@@ -6,6 +6,7 @@
 import io.audd.errors.AudDInvalidRequestError;
 import io.audd.errors.AudDSerializationError;
 import io.audd.internal.HttpClient;
+import io.audd.internal.Json;
 import io.audd.internal.ResponseDecoder;
 import io.audd.internal.RetryPolicy;
 import io.audd.models.CallbackEvent;
@@ -23,7 +24,7 @@
 
 /** Async streams namespace. Returns {@link CompletableFuture}s. */
 public final class AsyncStreams {
-    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final ObjectMapper MAPPER = Json.mapper();
     private static final int NO_CALLBACK_ERROR_CODE = 19;
 
     private final HttpClient http;