Releasing v4.11.0

CHANGELOG.md

@@ -1,3 +1,10 @@
+### v4.11.0 (2026-06-23)
+* * *
+### Bug Fixes:
+- Fixed JSON request body serialization where `Timestamp` parameters were sent in a human-readable format (e.g. `"expires_at":"2026-06-23 09:54:44.513"`) instead of Unix seconds. They are now serialized as numeric Unix seconds (e.g. `"expires_at":1782189229`), matching the form-url-encoded path and the format expected by the API. This affects all JSON content-type endpoints, such as [`create_promotional_grant`](https://apidocs.chargebee.com/docs/api/promotional_grants/create-promotional-grant) in [`PromotionalGrant`](https://apidocs.chargebee.com/docs/api/promotional_grants).
+
+
+
 ### v4.10.0 (2026-06-12)
 * * *
 ### New Resources:

VERSION

@@ -1 +1 @@
-4.10.0
+4.11.0

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "com.chargebee"
-version = "4.10.0"
+version = "4.11.0"
 description = "Java client library for ChargeBee"
 
 // Project metadata

src/main/java/com/chargebee/v4/internal/JsonUtil.java

@@ -1,15 +1,19 @@
 package com.chargebee.v4.internal;
 
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
 import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
-import com.google.gson.JsonNull;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import com.google.gson.JsonPrimitive;
+import com.google.gson.JsonSerializer;
 
 import java.math.BigDecimal;
 import java.sql.Timestamp;
+import java.text.SimpleDateFormat;
 import java.util.ArrayList;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -19,6 +23,29 @@
 /** Gson-backed JSON parsing utility. */
 public class JsonUtil {
 
+    /**
+     * Gson instance configured with Chargebee-specific serializers so that
+     * non-trivial leaf types are emitted in the shape the Chargebee API expects:
+     * <ul>
+     *   <li>{@link Timestamp} → Unix seconds (JSON number)</li>
+     *   <li>{@link Date}      → {@code "yyyy-MM-dd"} JSON string</li>
+     *   <li>{@link Enum}      → lowercase {@code name()} JSON string</li>
+     * </ul>
+     * HTML escaping is disabled so characters like {@code <}, {@code >}, {@code &}
+     * pass through verbatim (matches the previous {@code JsonElement.toString()} behavior).
+     */
+    private static final Gson GSON = new GsonBuilder()
+            .disableHtmlEscaping()
+            .serializeNulls()
+            .registerTypeAdapter(Timestamp.class,
+                    (JsonSerializer<Timestamp>) (src, t, c) -> new JsonPrimitive(src.getTime()))
+            .registerTypeAdapter(Date.class,
+                    (JsonSerializer<Date>) (src, t, c) ->
+                            new JsonPrimitive(new SimpleDateFormat("yyyy-MM-dd").format(src)))
+            .registerTypeHierarchyAdapter(Enum.class,
+                    (JsonSerializer<Enum<?>>) (src, t, c) -> new JsonPrimitive(src.name().toLowerCase()))
+            .create();
+
     private JsonUtil() {}
 
     // --- Parse entry points ---
@@ -320,25 +347,16 @@ public static Map<String, Object> extractConsentFields(JsonObject obj, Set<Strin
 
     // --- Serialization ---
 
-    /** Serializes a Map to a JSON string. */
-    @SuppressWarnings("unchecked")
+    /** Serializes a Map to a JSON string using the configured {@link #GSON} instance. */
     public static String toJson(Map<String, Object> map) {
         if (map == null || map.isEmpty()) return "{}";
-        JsonObject obj = new JsonObject();
-        for (Map.Entry<String, Object> entry : map.entrySet()) {
-            obj.add(entry.getKey(), toJsonElement(entry.getValue()));
-        }
-        return obj.toString();
+        return GSON.toJson(map);
     }
 
-    /** Serializes a List to a JSON string. */
+    /** Serializes a List to a JSON string using the configured {@link #GSON} instance. */
     public static String toJson(List<?> list) {
         if (list == null || list.isEmpty()) return "[]";
-        JsonArray array = new JsonArray();
-        for (Object item : list) {
-            array.add(toJsonElement(item));
-        }
-        return array.toString();
+        return GSON.toJson(list);
     }
 
     // --- Internal helpers ---
@@ -365,27 +383,4 @@ private static Object toJavaValue(JsonElement value) {
         }
         return null;
     }
-
-    @SuppressWarnings("unchecked")
-    private static JsonElement toJsonElement(Object value) {
-        if (value == null) return JsonNull.INSTANCE;
-        if (value instanceof String) return new JsonPrimitive((String) value);
-        if (value instanceof Number) return new JsonPrimitive((Number) value);
-        if (value instanceof Boolean) return new JsonPrimitive((Boolean) value);
-        if (value instanceof Map) {
-            JsonObject obj = new JsonObject();
-            for (Map.Entry<String, Object> entry : ((Map<String, Object>) value).entrySet()) {
-                obj.add(entry.getKey(), toJsonElement(entry.getValue()));
-            }
-            return obj;
-        }
-        if (value instanceof List) {
-            JsonArray array = new JsonArray();
-            for (Object item : (List<?>) value) {
-                array.add(toJsonElement(item));
-            }
-            return array;
-        }
-        return new JsonPrimitive(value.toString());
-    }
 }

src/test/java/com/chargebee/v4/internal/JsonUtilTest.java

@@ -6,6 +6,7 @@
 
 import java.math.BigDecimal;
 import java.sql.Timestamp;
+import java.util.Date;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -16,6 +17,8 @@
 @DisplayName("JsonUtil Tests")
 class JsonUtilTest {
 
+    private enum Status { ACTIVE, IN_TRIAL, NON_RENEWING }
+
     // ========== parse / parseToArray ==========
     @Nested
     @DisplayName("parse Tests")
@@ -644,6 +647,142 @@ class ToJsonTests {
         }
     }
 
+    // ========== Timestamp / Date / Enum serialization ==========
+    // Regression coverage for a bug where java.sql.Timestamp values were emitted
+    // in human-readable form (e.g. "2026-06-23 09:54:44.513") because they fell
+    // through to the default `value.toString()` branch in toJsonElement(...).
+    // The JSON path emits Timestamp as Unix milliseconds (Timestamp.getTime()).
+    @Nested
+    @DisplayName("Timestamp / Date / Enum serialization")
+    class TimestampDateEnumSerialization {
+
+        @Test void timestampIsEmittedAsUnixMillisNumber() {
+            Timestamp ts = Timestamp.from(java.time.Instant.parse("2026-06-23T09:54:44Z"));
+            long expected = ts.getTime();
+            Map<String, Object> map = new java.util.LinkedHashMap<>();
+            map.put("expires_at", ts);
+
+            String json = JsonUtil.toJson(map);
+            JsonObject parsed = JsonUtil.parse(json);
+
+            assertEquals(expected, JsonUtil.getLong(parsed, "expires_at"),
+                    "Timestamp must be serialized as Unix-millis number");
+            assertTrue(json.contains("\"expires_at\":" + expected),
+                    "JSON should contain numeric expires_at. Got: " + json);
+            // And must NOT be a quoted string of any shape.
+            assertFalse(json.matches(".*\"expires_at\"\\s*:\\s*\"[^\"]+\".*"),
+                    "Timestamp must not be quoted. Got: " + json);
+            assertFalse(json.contains(ts.toString()),
+                    "JSON must not contain Timestamp.toString() output. Got: " + json);
+        }
+
+        @Test void dateIsEmittedAsYyyyMmDdString() {
+            java.util.Calendar cal = java.util.Calendar.getInstance(java.util.TimeZone.getDefault());
+            cal.clear();
+            cal.set(2025, java.util.Calendar.DECEMBER, 31, 10, 0, 0);
+            Date d = cal.getTime();
+            String expected = new java.text.SimpleDateFormat("yyyy-MM-dd").format(d);
+
+            Map<String, Object> map = new java.util.HashMap<>();
+            map.put("trial_end_date", d);
+
+            String json = JsonUtil.toJson(map);
+            assertEquals(expected, JsonUtil.getString(JsonUtil.parse(json), "trial_end_date"));
+        }
+
+        @Test void enumIsEmittedAsLowercaseString() {
+            Map<String, Object> map = new java.util.HashMap<>();
+            map.put("status", Status.IN_TRIAL);
+
+            String json = JsonUtil.toJson(map);
+            assertEquals("in_trial", JsonUtil.getString(JsonUtil.parse(json), "status"));
+        }
+
+        @Test void timestampNestedInsideMapIsConverted() {
+            Timestamp ts = Timestamp.from(java.time.Instant.parse("2026-01-01T00:00:00Z"));
+            long expected = ts.getTime();
+
+            Map<String, Object> inner = new java.util.LinkedHashMap<>();
+            inner.put("seen_at", ts);
+            Map<String, Object> outer = new java.util.LinkedHashMap<>();
+            outer.put("metadata", inner);
+
+            JsonObject parsed = JsonUtil.parse(JsonUtil.toJson(outer));
+            JsonObject got = JsonUtil.getJsonObject(parsed, "metadata");
+            assertNotNull(got);
+            assertEquals(expected, JsonUtil.getLong(got, "seen_at"));
+        }
+
+        @Test void timestampInsideListIsConvertedPerElement() {
+            Timestamp t1 = Timestamp.from(java.time.Instant.parse("2026-01-01T00:00:00Z"));
+            Timestamp t2 = Timestamp.from(java.time.Instant.parse("2026-02-01T00:00:00Z"));
+
+            Map<String, Object> map = new java.util.HashMap<>();
+            map.put("checkpoints", java.util.Arrays.asList(t1, t2));
+
+            String json = JsonUtil.toJson(map);
+            JsonArray arr = JsonUtil.getJsonArray(JsonUtil.parse(json), "checkpoints");
+            assertNotNull(arr);
+            assertEquals(2, arr.size());
+            assertEquals(t1.getTime(), arr.get(0).getAsLong());
+            assertEquals(t2.getTime(), arr.get(1).getAsLong());
+        }
+
+        @Test void objectArrayIsConvertedRecursively() {
+            Timestamp ts = Timestamp.from(java.time.Instant.parse("2026-03-01T00:00:00Z"));
+
+            Map<String, Object> map = new java.util.HashMap<>();
+            map.put("mixed", new Object[] { ts, "hello", 7 });
+
+            JsonArray arr = JsonUtil.getJsonArray(JsonUtil.parse(JsonUtil.toJson(map)), "mixed");
+            assertNotNull(arr);
+            assertEquals(3, arr.size());
+            assertEquals(ts.getTime(), arr.get(0).getAsLong());
+            assertEquals("hello", arr.get(1).getAsString());
+            assertEquals(7, arr.get(2).getAsInt());
+        }
+
+        @Test void deeplyNestedMapAndListAreFullyTraversed() {
+            Timestamp ts = Timestamp.from(java.time.Instant.parse("2026-04-15T12:00:00Z"));
+            long expected = ts.getTime();
+
+            Map<String, Object> inner = new java.util.HashMap<>();
+            inner.put("at", ts);
+            inner.put("status", Status.ACTIVE);
+
+            Map<String, Object> outer = new java.util.HashMap<>();
+            outer.put("events", java.util.Arrays.asList(inner, java.util.Arrays.asList(ts, "x")));
+
+            JsonObject parsed = JsonUtil.parse(JsonUtil.toJson(outer));
+            JsonArray events = JsonUtil.getJsonArray(parsed, "events");
+            assertNotNull(events);
+
+            JsonObject first = events.get(0).getAsJsonObject();
+            assertEquals(expected, JsonUtil.getLong(first, "at"));
+            assertEquals("active", JsonUtil.getString(first, "status"));
+
+            JsonArray second = events.get(1).getAsJsonArray();
+            assertEquals(expected, second.get(0).getAsLong());
+            assertEquals("x", second.get(1).getAsString());
+        }
+
+        @Test void numericTypesAreStillEmittedAsJsonNumbers() {
+            Map<String, Object> map = new java.util.LinkedHashMap<>();
+            map.put("int_val", 42);
+            map.put("long_val", 1234567890123L);
+            map.put("double_val", 3.14);
+            map.put("decimal_val", new BigDecimal("19.99"));
+            map.put("bool_val", true);
+
+            JsonObject parsed = JsonUtil.parse(JsonUtil.toJson(map));
+            assertEquals(42, JsonUtil.getInteger(parsed, "int_val"));
+            assertEquals(1234567890123L, JsonUtil.getLong(parsed, "long_val"));
+            assertEquals(3.14, JsonUtil.getDouble(parsed, "double_val"), 0.0001);
+            assertEquals(new BigDecimal("19.99"), JsonUtil.getBigDecimal(parsed, "decimal_val"));
+            assertTrue(JsonUtil.getBoolean(parsed, "bool_val"));
+        }
+    }
+
     // ========== Edge Cases ==========
     @Nested
     @DisplayName("Edge Cases")