Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(sdk): decode unknown enum values to UNKNOWN in the Java SDK
Yudhi Armyndharisca75c85c01cc
diff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjsindex ec518a3d6..511a5fc8b 100644--- a/scripts/check-contract-shapes.mjs+++ b/scripts/check-contract-shapes.mjs@@ -19,7 +19,8 @@* and optionality only, so the literal sets themselves are ungated on the TS clients. Everywhere* else the vocabulary IS compared member by member: Python Literals, Go const blocks and Java* enum constants (by their `@SerializedName`, or the constant's own name when it has none, which- * is what Gson emits), whether the field carries one member or a list of them.+ * is what Gson emits; a bare `UNKNOWN` is the decode-only sentinel and is skipped), whether the+ * field carries one member or a list of them.** One exception, in Java only: Gson serializes an enum constant by name, i.e. as a JSON string, so* a NUMERIC enum cannot be modelled as a Java enum without a custom adapter: the wire would carry@@ -1010,7 +1011,9 @@ export function parseJavaTypes(sources) {continue;}const bare = part.replace(/@\w+\([^)]*\)/g, '').trim().match(/^([A-Z][A-Z0-9_]*)$/);- if (bare) members.push(bare[1]);+ // A bare UNKNOWN is the client-side sentinel the SDK decodes an unrecognised token to, not+ // a wire member. An annotated @SerializedName("unknown") is a real member and counts above.+ if (bare && bare[1] !== 'UNKNOWN') members.push(bare[1]);}if (members.length) enums[m[1]] = `enum(${sortEnumMembers([...new Set(members)]).join(',')})`;}diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjsindex 87f19fb2b..3c26da3a8 100644--- a/scripts/check-contract-shapes.spec.mjs+++ b/scripts/check-contract-shapes.spec.mjs@@ -242,6 +242,24 @@ test('parseJavaTypes: enum constants resolve to their wire values, annotated orassert.equal(s.shades.token, 'array<enum(BLUE,RED)>');});+test('parseJavaTypes: a bare UNKNOWN sentinel is not a wire member, an annotated "unknown" is', () => {+ const src = [+ 'public enum Status {',+ ' @SerializedName("ready") READY,',+ ' /** Decoded when the gateway sends a newer value. */',+ ' UNKNOWN',+ '}',+ 'public enum Kind {',+ ' @SerializedName("chat") CHAT,',+ ' @SerializedName("unknown") UNKNOWN',+ '}',+ 'public record Sample(Status status, Kind kind) {}',+ ].join('\n');+ const s = parseJavaTypes([src]).Sample;+ assert.equal(s.status.token, 'enum(ready)');+ assert.equal(s.kind.token, 'enum(chat,unknown)');+});+test('isSimpleToken-gated diffing reaches inside an array of enum members', () => {const hand = { events: { optional: false, token: 'array<enum(a,b)>' } };const schema = { type: 'object', required: ['events'], properties: { events: { type: 'array', items: { enum: ['a', 'c'] } } } };diff --git a/sdk/java/README.md b/sdk/java/README.mdindex 9bceffe51..e6f7f43e1 100644--- a/sdk/java/README.md+++ b/sdk/java/README.md@@ -82,6 +82,12 @@ intentionally not exposed; all user-facing resources are.webhook's filters unchanged. To remove every filter, pass`new WebhookFilters(List.of())` instead.+A response enum value newer than this SDK decodes to that enum's `UNKNOWN`+constant (for example `SessionStatus.UNKNOWN`) rather than `null`, so give a+`switch` over one a `default` branch. `WebhookEvent`, `ProxyType` and+`MessageDirection` are also sent in requests and have no `UNKNOWN`: an+unrecognised value there still decodes to `null`.+## Error handlingErrors are a typed, unchecked hierarchy — branch with `instanceof` or ondiff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.java b/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.javanew file mode 100644index 000000000..9150ce8c0--- /dev/null+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.java@@ -0,0 +1,53 @@+package com.rmyndharis.openwa;++import com.google.gson.Gson;+import com.google.gson.TypeAdapter;+import com.google.gson.TypeAdapterFactory;+import com.google.gson.reflect.TypeToken;+import com.google.gson.stream.JsonReader;+import com.google.gson.stream.JsonToken;+import com.google.gson.stream.JsonWriter;+import java.io.IOException;++/**+ * Decodes a wire token this SDK does not know to the enum's {@code UNKNOWN} constant instead of+ * null, so a value the gateway added later is not mistaken for an absent field. Enums without an+ * {@code UNKNOWN} constant keep Gson's default, and writing is unchanged.+ */+final class LenientEnumTypeAdapterFactory implements TypeAdapterFactory {+ @Override+ @SuppressWarnings("unchecked")+ public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type) {+ Class<? super T> raw = type.getRawType();+ if (!raw.isEnum()) {+ return null;+ }+ T unknown = null;+ for (Object constant : raw.getEnumConstants()) {+ if (((Enum<?>) constant).name().equals("UNKNOWN")) {+ unknown = (T) constant;+ }+ }+ if (unknown == null) {+ return null;+ }+ TypeAdapter<T> delegate = gson.getDelegateAdapter(this, type);+ T fallback = unknown;+ return new TypeAdapter<T>() {+ @Override+ public void write(JsonWriter out, T value) throws IOException {+ delegate.write(out, value);+ }++ @Override+ public T read(JsonReader in) throws IOException {+ if (in.peek() == JsonToken.NULL) {+ in.nextNull();+ return null;+ }+ T value = delegate.read(in);+ return value != null ? value : fallback;+ }+ };+ }+}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.javaindex f1063a1b5..212f2851d 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java@@ -53,7 +53,10 @@ import java.util.Map;* }</pre>*/public final class OpenWAClient {- private final Gson gson = new Gson();+ // An unrecognised enum token decodes to that enum's UNKNOWN constant rather than null.+ private final Gson gson = new GsonBuilder()+ .registerTypeAdapterFactory(new LenientEnumTypeAdapterFactory())+ .create();// Used for the two body types listed in bodySerializer(), never the shared default. Emitting an// explicit null needs two things that pull in opposite directions: a serializer that decidesdiff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.javaindex 5e878f401..d193b6fde 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java@@ -6,5 +6,7 @@ import com.google.gson.annotations.SerializedName;public enum AccountRestrictionKind {@SerializedName("reachout_timelock") REACHOUT_TIMELOCK,@SerializedName("tos_block") TOS_BLOCK,- @SerializedName("proxy_block") PROXY_BLOCK+ @SerializedName("proxy_block") PROXY_BLOCK,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.javaindex 9052d2601..2c21da0a9 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java@@ -8,5 +8,7 @@ public enum BatchLifecycleStatus {@SerializedName("processing") PROCESSING,@SerializedName("completed") COMPLETED,@SerializedName("failed") FAILED,- @SerializedName("cancelled") CANCELLED+ @SerializedName("cancelled") CANCELLED,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.javaindex dedf6a551..0c48207d9 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java@@ -7,5 +7,7 @@ public enum BatchMessageStatus {@SerializedName("pending") PENDING,@SerializedName("sent") SENT,@SerializedName("failed") FAILED,- @SerializedName("cancelled") CANCELLED+ @SerializedName("cancelled") CANCELLED,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.javaindex deb852ee7..e8d12bd38 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java@@ -13,5 +13,7 @@ public enum DeliveryStatus {@SerializedName("read")READ,@SerializedName("failed")- FAILED+ FAILED,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.javaindex 00c424368..89b33ec8a 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java@@ -5,5 +5,7 @@ import com.google.gson.annotations.SerializedName;/** Who may add participants to a group. */public enum MemberAddMode {@SerializedName("all") ALL,- @SerializedName("admins") ADMINS+ @SerializedName("admins") ADMINS,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.javaindex 83d5e1117..d105d6af5 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java@@ -12,5 +12,7 @@ public enum MembershipRequestMethod {@SerializedName("linked_group_join")LINKED_GROUP_JOIN,@SerializedName("non_admin_add")- NON_ADMIN_ADD+ NON_ADMIN_ADD,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.javaindex f5014a195..88bb49e1f 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java@@ -8,5 +8,7 @@ public enum PresenceState {@SerializedName("unavailable") UNAVAILABLE,@SerializedName("composing") COMPOSING,@SerializedName("recording") RECORDING,- @SerializedName("paused") PAUSED+ @SerializedName("paused") PAUSED,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.javaindex 6fa2cf8d8..3cb0bd32f 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java@@ -22,5 +22,7 @@ public enum SessionStatus {@SerializedName("action_required")ACTION_REQUIRED,@SerializedName("failed")- FAILED+ FAILED,+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */+ UNKNOWN}diff --git a/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java b/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.javaindex 03583fd20..af812f50e 100644--- a/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java+++ b/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java@@ -1,20 +1,26 @@package com.rmyndharis.openwa;import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertNull;import com.google.gson.Gson;import com.google.gson.GsonBuilder;+import com.rmyndharis.openwa.http.HttpMethod;+import com.rmyndharis.openwa.model.AccountRestriction;import com.rmyndharis.openwa.model.AccountRestrictionKind;import com.rmyndharis.openwa.model.BatchLifecycleStatus;import com.rmyndharis.openwa.model.BatchMessageResult;import com.rmyndharis.openwa.model.BatchMessageStatus;import com.rmyndharis.openwa.model.ChatHistoryMessage;import com.rmyndharis.openwa.model.ChatKind;+import com.rmyndharis.openwa.model.GroupInfo;import com.rmyndharis.openwa.model.MemberAddMode;import com.rmyndharis.openwa.model.MessageType;+import com.rmyndharis.openwa.model.ParticipantPresence;import com.rmyndharis.openwa.model.PresenceState;import com.rmyndharis.openwa.model.SessionResponse;import com.rmyndharis.openwa.model.SessionStatus;+import com.rmyndharis.openwa.support.MockTransport;import org.junit.jupiter.api.Test;/**@@ -88,4 +94,42 @@ class EnumWireTest {assertEquals(MemberAddMode.ADMINS, g.memberAddMode());}++ @Test+ void clientDecodesAnUnrecognisedTokenToUnknownNotNull() {+ MockTransport tx = new MockTransport();+ OpenWAClient client = new OpenWAClient(+ ClientConfig.builder().baseUrl("https://h").apiKey("owa_k1_x").transport(tx).build());++ tx.respond(200, "{\"id\":\"s\",\"name\":\"n\",\"status\":\"brand_new_state\",\"engineLoaded\":true,"+ + "\"createdAt\":\"t\",\"updatedAt\":\"t\"}");+ assertEquals(SessionStatus.UNKNOWN, client.sessions.get("s").status());++ tx.respond(200, "{\"chatId\":\"c\",\"status\":\"later\"}");+ assertEquals(BatchMessageStatus.UNKNOWN,+ client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());+ tx.respond(200, "{\"state\":\"later\"}");+ assertEquals(PresenceState.UNKNOWN,+ client.request(HttpMethod.GET, "/x", null, null, ParticipantPresence.class).state());+ tx.respond(200, "{\"kind\":\"later\"}");+ assertEquals(AccountRestrictionKind.UNKNOWN,+ client.request(HttpMethod.GET, "/x", null, null, AccountRestriction.class).kind());+ tx.respond(200, "{\"memberAddMode\":\"later\"}");+ assertEquals(MemberAddMode.UNKNOWN,+ client.request(HttpMethod.GET, "/x", null, null, GroupInfo.class).memberAddMode());+ tx.respond(200, "{\"type\":\"future_type\",\"kind\":\"unknown\"}");+ ChatHistoryMessage m = client.request(HttpMethod.GET, "/x", null, null, ChatHistoryMessage.class);+ assertEquals(MessageType.UNKNOWN, m.type());+ assertEquals(ChatKind.UNKNOWN, m.kind());++ // A null or absent value is still null, and a known token still decodes to its constant.+ tx.respond(200, "{\"chatId\":\"c\",\"status\":null}");+ assertNull(client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());+ tx.respond(200, "{\"chatId\":\"c\",\"status\":\"sent\"}");+ assertEquals(BatchMessageStatus.SENT,+ client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());+ tx.respond(200, "{\"id\":\"s\"}");+ assertNull(client.sessions.get("s").status());+ }+}