diff --git a/AGENTS.md b/AGENTS.md index aa1d119e..818fb939 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Fetch the endpoint spec first (see Crowdin API reference below). Then: 1. Implement the method on `Api extends CrowdinApi`: build URLs from `this.url`, add query params with `HttpRequestConfig.buildUrlParams(...)` (overloads cap at 14 pairs), declare `throws HttpException, HttpBadRequestException`, and return `ResponseObject` / `ResponseList` (`Void.class` for empty responses). 2. Models are Lombok `@Data` POJOs in `/model/` — write no getters, setters, or equals by hand. Jackson is configured for field-only visibility and the codebase uses no `@JsonProperty`: field names must match the API JSON keys exactly, or values silently drop. Every list endpoint needs a `ResponseList` with a hand-written static `to(...)` mapping to `ResponseList.of(...)`. Params classes extending `Pagination` need `@EqualsAndHashCode(callSuper = true)`. -3. Enums implement `EnumConverter`: an instance `to(...)` plus a **static** `from(String)` that the deserializer finds by reflection — a missing `from` fails at runtime, not compile time. Polymorphic models need a deserializer registered in `JacksonJsonTransformer`; fields the API returns as `[]` instead of an object need `@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)`. +3. Enums implement `EnumConverter`: an instance `to(...)` plus a **static** `from(String)` that the deserializer finds by reflection — a missing `from` fails at runtime, not compile time. Polymorphic models need a deserializer registered in `JacksonJsonTransformer`. The API sends some empty objects as `[]`; `cleanObjectMapper` in `JacksonJsonTransformer` reads that as `null` for every `Map` and POJO field, so build any new deserializer's mapper from `cleanObjectMapper` to inherit it. 4. For a new resource, register it in `Client.java` with four edits: the import (alphabetical), a `private final Api Api;` field, and its construction in both constructors (`(Credentials)` and `(Credentials, ClientConfig)`). `@Getter` generates the accessor. 5. Test by extending `TestClient` (the test class is itself a client wired to `TestHttpClient`): implement `getMocks()` returning `RequestMock.build(url, method, requestFile, responseFile)` entries, add fixture JSON under `src/test/resources/api//`, and call `this.getApi()...`. Mocks match query params exactly (pre-encode spaces as `%20`) and compare the serialized request body against the fixture — a new optional query param must stay absent when null or existing mocks for that URL break. 6. Javadoc every public method with `@param`/`@return` and a `@see` list linking both the developer.crowdin.com and enterprise operation URLs (CI publishes Javadoc). diff --git a/src/main/java/com/crowdin/client/advisors/model/AdvisorInsight.java b/src/main/java/com/crowdin/client/advisors/model/AdvisorInsight.java index f6bdefc4..fca5379f 100644 --- a/src/main/java/com/crowdin/client/advisors/model/AdvisorInsight.java +++ b/src/main/java/com/crowdin/client/advisors/model/AdvisorInsight.java @@ -1,7 +1,5 @@ package com.crowdin.client.advisors.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Date; @@ -23,6 +21,5 @@ public class AdvisorInsight { private List recommendations; private Date checkedAt; private AdvisorAiRun lastAiRun; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map payload; } diff --git a/src/main/java/com/crowdin/client/advisors/model/AdvisorInsightRecommendation.java b/src/main/java/com/crowdin/client/advisors/model/AdvisorInsightRecommendation.java index 85ceb8fc..d1c460ce 100644 --- a/src/main/java/com/crowdin/client/advisors/model/AdvisorInsightRecommendation.java +++ b/src/main/java/com/crowdin/client/advisors/model/AdvisorInsightRecommendation.java @@ -1,7 +1,5 @@ package com.crowdin.client.advisors.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Map; @@ -11,6 +9,5 @@ public class AdvisorInsightRecommendation { private String id; private Boolean primary; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map params; } diff --git a/src/main/java/com/crowdin/client/core/http/impl/json/EmptyArrayToNullDeserializer.java b/src/main/java/com/crowdin/client/core/http/impl/json/EmptyArrayToNullDeserializer.java index 5bdbdb25..cd787aeb 100644 --- a/src/main/java/com/crowdin/client/core/http/impl/json/EmptyArrayToNullDeserializer.java +++ b/src/main/java/com/crowdin/client/core/http/impl/json/EmptyArrayToNullDeserializer.java @@ -9,6 +9,11 @@ import java.io.IOException; import java.util.Collection; +/** + * @deprecated no longer needed: {@link JacksonJsonTransformer} reads an empty array as {@code null} + * for every Map and POJO field + */ +@Deprecated public class EmptyArrayToNullDeserializer extends StdDeserializer implements ContextualDeserializer { private JavaType type; diff --git a/src/main/java/com/crowdin/client/core/http/impl/json/JacksonJsonTransformer.java b/src/main/java/com/crowdin/client/core/http/impl/json/JacksonJsonTransformer.java index 80f66b29..98504cec 100644 --- a/src/main/java/com/crowdin/client/core/http/impl/json/JacksonJsonTransformer.java +++ b/src/main/java/com/crowdin/client/core/http/impl/json/JacksonJsonTransformer.java @@ -16,7 +16,10 @@ import com.fasterxml.jackson.annotation.PropertyAccessor; import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.cfg.CoercionAction; +import com.fasterxml.jackson.databind.cfg.CoercionInputShape; import com.fasterxml.jackson.databind.module.SimpleModule; +import com.fasterxml.jackson.databind.type.LogicalType; import com.fasterxml.jackson.databind.util.StdDateFormat; import lombok.SneakyThrows; @@ -30,6 +33,13 @@ public class JacksonJsonTransformer implements JsonTransformer { public JacksonJsonTransformer() { ObjectMapper cleanObjectMapper = new ObjectMapper() .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); + + // the API sends some empty objects as []; read them as null (set before copy() so derived mappers inherit it) + cleanObjectMapper.coercionConfigFor(LogicalType.Map) + .setCoercion(CoercionInputShape.EmptyArray, CoercionAction.AsNull); + cleanObjectMapper.coercionConfigFor(LogicalType.POJO) + .setCoercion(CoercionInputShape.EmptyArray, CoercionAction.AsNull); + SimpleModule enumModule = new SimpleModule() .addDeserializer(Enum.class, new EnumDeserializer()); diff --git a/src/main/java/com/crowdin/client/organization/model/ExternalQaCheck.java b/src/main/java/com/crowdin/client/organization/model/ExternalQaCheck.java index 75a028cb..2ee572b3 100644 --- a/src/main/java/com/crowdin/client/organization/model/ExternalQaCheck.java +++ b/src/main/java/com/crowdin/client/organization/model/ExternalQaCheck.java @@ -1,7 +1,5 @@ package com.crowdin.client.organization.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Date; @@ -13,7 +11,6 @@ public class ExternalQaCheck { private Long id; private String name; private String description; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map config; private Date createdAt; private Date updatedAt; diff --git a/src/main/java/com/crowdin/client/projectsgroups/model/ProjectSettings.java b/src/main/java/com/crowdin/client/projectsgroups/model/ProjectSettings.java index deda6ebe..6d3dcbb2 100644 --- a/src/main/java/com/crowdin/client/projectsgroups/model/ProjectSettings.java +++ b/src/main/java/com/crowdin/client/projectsgroups/model/ProjectSettings.java @@ -1,8 +1,6 @@ package com.crowdin.client.projectsgroups.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; import com.crowdin.client.languages.model.Language; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import lombok.EqualsAndHashCode; import lombok.ToString; @@ -42,18 +40,13 @@ public class ProjectSettings extends Project { private NotificationSettings notificationSettings; private Long defaultTmId; private Long defaultGlossaryId; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map assignedTms; private List assignedGlossaries; private List assignedStyleGuides; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private TmPenalties tmPenalties; private Boolean normalizePlaceholder; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private TmPreTranslate tmPreTranslate; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private MtPreTranslate mtPreTranslate; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private AiPreTranslate aiPreTranslate; /** * @deprecated no longer part of the documented API diff --git a/src/main/java/com/crowdin/client/sourcefiles/model/FileInfo.java b/src/main/java/com/crowdin/client/sourcefiles/model/FileInfo.java index 5374a1c8..a06efa86 100644 --- a/src/main/java/com/crowdin/client/sourcefiles/model/FileInfo.java +++ b/src/main/java/com/crowdin/client/sourcefiles/model/FileInfo.java @@ -1,7 +1,5 @@ package com.crowdin.client.sourcefiles.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Map; @@ -22,6 +20,5 @@ public class FileInfo { /** * Custom fields (Enterprise only) */ - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map fields; } diff --git a/src/main/java/com/crowdin/client/sourcestrings/model/UploadStringsProgress.java b/src/main/java/com/crowdin/client/sourcestrings/model/UploadStringsProgress.java index 55c30d5e..8b0fa5de 100644 --- a/src/main/java/com/crowdin/client/sourcestrings/model/UploadStringsProgress.java +++ b/src/main/java/com/crowdin/client/sourcestrings/model/UploadStringsProgress.java @@ -1,8 +1,6 @@ package com.crowdin.client.sourcestrings.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; import com.crowdin.client.sourcefiles.model.UpdateOption; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Date; @@ -28,7 +26,6 @@ public static class Attributes { private String fileType; private Integer parserVersion; private List labelIds; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private ImportOptions importOptions; private Boolean updateStrings; private Boolean cleanupMode; diff --git a/src/main/java/com/crowdin/client/translations/model/ImportTranslationsReportResponse.java b/src/main/java/com/crowdin/client/translations/model/ImportTranslationsReportResponse.java index b68f0025..380c8340 100644 --- a/src/main/java/com/crowdin/client/translations/model/ImportTranslationsReportResponse.java +++ b/src/main/java/com/crowdin/client/translations/model/ImportTranslationsReportResponse.java @@ -1,7 +1,5 @@ package com.crowdin.client.translations.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.List; @@ -17,9 +15,7 @@ public class ImportTranslationsReportResponse { public static class TargetLanguage { private String id; private List files; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skipped; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skippedQaCheckCategories; } diff --git a/src/main/java/com/crowdin/client/translations/model/ImportTranslationsStringsBasedReportResponse.java b/src/main/java/com/crowdin/client/translations/model/ImportTranslationsStringsBasedReportResponse.java index 2813fd99..b75b6bf0 100644 --- a/src/main/java/com/crowdin/client/translations/model/ImportTranslationsStringsBasedReportResponse.java +++ b/src/main/java/com/crowdin/client/translations/model/ImportTranslationsStringsBasedReportResponse.java @@ -1,7 +1,5 @@ package com.crowdin.client.translations.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.List; @@ -17,9 +15,7 @@ public class ImportTranslationsStringsBasedReportResponse { public static class TargetLanguage { private String id; private List branches; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skipped; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skippedQaCheckCategories; } diff --git a/src/main/java/com/crowdin/client/translations/model/PreTranslationReportResponse.java b/src/main/java/com/crowdin/client/translations/model/PreTranslationReportResponse.java index 496d588a..8c095bdd 100644 --- a/src/main/java/com/crowdin/client/translations/model/PreTranslationReportResponse.java +++ b/src/main/java/com/crowdin/client/translations/model/PreTranslationReportResponse.java @@ -1,7 +1,5 @@ package com.crowdin.client.translations.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.List; import java.util.Map; @@ -17,9 +15,7 @@ public class PreTranslationReportResponse { public static class TargetLanguage { private String id; private List files; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skipped; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map skippedQaCheckCategories; } diff --git a/src/main/java/com/crowdin/client/users/model/TranslatorRole.java b/src/main/java/com/crowdin/client/users/model/TranslatorRole.java index 0d2cbda9..facb7462 100644 --- a/src/main/java/com/crowdin/client/users/model/TranslatorRole.java +++ b/src/main/java/com/crowdin/client/users/model/TranslatorRole.java @@ -1,12 +1,9 @@ package com.crowdin.client.users.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; @Data public class TranslatorRole { private TranslatorRoleName name; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private TranslatorRolePermissions permissions; } diff --git a/src/main/java/com/crowdin/client/users/model/TranslatorRolePermissions.java b/src/main/java/com/crowdin/client/users/model/TranslatorRolePermissions.java index fa532ecd..11b93f20 100644 --- a/src/main/java/com/crowdin/client/users/model/TranslatorRolePermissions.java +++ b/src/main/java/com/crowdin/client/users/model/TranslatorRolePermissions.java @@ -1,8 +1,6 @@ package com.crowdin.client.users.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; import com.crowdin.client.core.model.LanguageAccessRule; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Map; @@ -10,6 +8,5 @@ @Data public class TranslatorRolePermissions { private boolean allLanguages; - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map languagesAccess; } diff --git a/src/main/java/com/crowdin/client/webhooks/model/OrganizationWebhook.java b/src/main/java/com/crowdin/client/webhooks/model/OrganizationWebhook.java index 78641322..625a72d7 100644 --- a/src/main/java/com/crowdin/client/webhooks/model/OrganizationWebhook.java +++ b/src/main/java/com/crowdin/client/webhooks/model/OrganizationWebhook.java @@ -1,7 +1,5 @@ package com.crowdin.client.webhooks.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Date; @@ -18,7 +16,6 @@ public class OrganizationWebhook { * Webhook headers. The API returns an empty array ({@code []}) when the webhook has no headers; * it is represented as {@code null}, the same as a missing value. */ - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map headers; private Object payload; private Boolean isActive; diff --git a/src/main/java/com/crowdin/client/webhooks/model/Webhook.java b/src/main/java/com/crowdin/client/webhooks/model/Webhook.java index 49976f75..e173e4b9 100644 --- a/src/main/java/com/crowdin/client/webhooks/model/Webhook.java +++ b/src/main/java/com/crowdin/client/webhooks/model/Webhook.java @@ -1,7 +1,5 @@ package com.crowdin.client.webhooks.model; -import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import lombok.Data; import java.util.Date; @@ -20,7 +18,6 @@ public class Webhook { * Webhook headers. The API returns an empty array ({@code []}) when the webhook has no headers; * it is represented as {@code null}, the same as a missing value. */ - @JsonDeserialize(using = EmptyArrayToNullDeserializer.class) private Map headers; private Object payload; private Boolean isActive; diff --git a/src/test/java/com/crowdin/client/core/http/impl/json/EmptyArrayCoercionTest.java b/src/test/java/com/crowdin/client/core/http/impl/json/EmptyArrayCoercionTest.java new file mode 100644 index 00000000..c1639e0a --- /dev/null +++ b/src/test/java/com/crowdin/client/core/http/impl/json/EmptyArrayCoercionTest.java @@ -0,0 +1,100 @@ +package com.crowdin.client.core.http.impl.json; + +import com.crowdin.client.glossaries.model.ConceptResponseObject; +import com.crowdin.client.glossaries.model.TermResponseObject; +import com.crowdin.client.projectsgroups.model.Project; +import com.crowdin.client.projectsgroups.model.ProjectResponseObject; +import com.crowdin.client.projectsgroups.model.ProjectSettings; +import com.crowdin.client.sourcestrings.model.SourceStringResponseObject; +import com.crowdin.client.users.model.UserResponseObject; +import com.fasterxml.jackson.databind.exc.MismatchedInputException; +import org.junit.jupiter.api.Test; + +import java.util.Collections; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The API sends some empty objects as {@code []}; the shared mapper must read them as {@code null} + * for every Map and POJO field, without per-field annotations. + */ +public class EmptyArrayCoercionTest { + + private final JacksonJsonTransformer transformer = new JacksonJsonTransformer(); + + @Test + public void projectFieldsEmptyArray() { + Project project = transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", ProjectResponseObject.class).getData(); + + assertEquals(1L, project.getId()); + assertNull(project.getFields()); + } + + @Test + public void projectSettingsFieldsEmptyArray() { + Project project = transformer.parse("{\"data\":{\"id\":1,\"languageMapping\":[],\"fields\":[]}}", ProjectResponseObject.class).getData(); + + assertInstanceOf(ProjectSettings.class, project); + assertNull(project.getFields()); + } + + @Test + public void projectSettingsObjectsEmptyArray() { + ProjectSettings settings = (ProjectSettings) transformer.parse("{\"data\":{\"id\":1,\"languageMapping\":[]," + + "\"assignedTms\":[],\"tmPreTranslate\":[],\"mtPreTranslate\":[],\"aiPreTranslate\":[]}}", ProjectResponseObject.class).getData(); + + assertNull(settings.getAssignedTms()); + assertNull(settings.getTmPreTranslate()); + assertNull(settings.getMtPreTranslate()); + assertNull(settings.getAiPreTranslate()); + } + + @Test + public void sourceStringFieldsEmptyArray() { + assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", SourceStringResponseObject.class).getData().getFields()); + } + + @Test + public void conceptFieldsEmptyArray() { + assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", ConceptResponseObject.class).getData().getFields()); + } + + @Test + public void termFieldsEmptyArray() { + assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", TermResponseObject.class).getData().getFields()); + } + + @Test + public void userFieldsEmptyArray() { + assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", UserResponseObject.class).getData().getFields()); + } + + @Test + public void nestedObjectEmptyArray() { + assertNull(transformer.parse("{\"data\":{\"id\":1,\"sourceLanguage\":[]}}", ProjectResponseObject.class).getData().getSourceLanguage()); + } + + @Test + public void populatedMapStillParses() { + Project project = transformer.parse("{\"data\":{\"id\":1,\"fields\":{\"slug\":\"value\"}}}", ProjectResponseObject.class).getData(); + + assertEquals(Collections.singletonMap("slug", "value"), project.getFields()); + } + + @Test + public void emptyArrayStaysEmptyListForListFields() { + Project project = transformer.parse("{\"data\":{\"id\":1,\"targetLanguageIds\":[]}}", ProjectResponseObject.class).getData(); + + assertTrue(project.getTargetLanguageIds().isEmpty()); + } + + @Test + public void nonEmptyArrayForMapStillFails() { + assertThrows(MismatchedInputException.class, + () -> transformer.parse("{\"data\":{\"id\":1,\"fields\":[1]}}", SourceStringResponseObject.class)); + } +}