logging = Optional.empty();
+
public Builder environment(Environment environment) {
this.environment = environment;
return this;
@@ -151,6 +161,14 @@ public Builder httpClient(OkHttpClient httpClient) {
return this;
}
+ /**
+ * Configure logging for the SDK. Silent by default — no log output unless explicitly configured.
+ */
+ public Builder logging(LogConfig logging) {
+ this.logging = Optional.of(logging);
+ return this;
+ }
+
public ClientOptions build() {
OkHttpClient.Builder httpClientBuilder =
this.httpClient != null ? this.httpClient.newBuilder() : new OkHttpClient.Builder();
@@ -170,11 +188,20 @@ public ClientOptions build() {
.addInterceptor(new RetryInterceptor(this.maxRetries));
}
+ Logger logger = Logger.from(this.logging);
+ httpClientBuilder.addInterceptor(new LoggingInterceptor(logger));
+
this.httpClient = httpClientBuilder.build();
this.timeout = Optional.of(httpClient.callTimeoutMillis() / 1000);
return new ClientOptions(
- environment, headers, headerSuppliers, httpClient, this.timeout.get(), this.maxRetries);
+ environment,
+ headers,
+ headerSuppliers,
+ httpClient,
+ this.timeout.get(),
+ this.maxRetries,
+ this.logging);
}
/**
@@ -188,6 +215,7 @@ public static Builder from(ClientOptions clientOptions) {
builder.headers.putAll(clientOptions.headers);
builder.headerSuppliers.putAll(clientOptions.headerSuppliers);
builder.maxRetries = clientOptions.maxRetries();
+ builder.logging = clientOptions.logging();
return builder;
}
}
diff --git a/src/main/java/com/icepanel/core/ConsoleLogger.java b/src/main/java/com/icepanel/core/ConsoleLogger.java
new file mode 100644
index 0000000..b6acee9
--- /dev/null
+++ b/src/main/java/com/icepanel/core/ConsoleLogger.java
@@ -0,0 +1,51 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import java.util.logging.Level;
+
+/**
+ * Default logger implementation that writes to the console using {@link java.util.logging.Logger}.
+ *
+ * Uses the "fern" logger name with a simple format of "LEVEL - message".
+ */
+public final class ConsoleLogger implements ILogger {
+
+ private static final java.util.logging.Logger logger = java.util.logging.Logger.getLogger("fern");
+
+ static {
+ if (logger.getHandlers().length == 0) {
+ java.util.logging.ConsoleHandler handler = new java.util.logging.ConsoleHandler();
+ handler.setFormatter(new java.util.logging.SimpleFormatter() {
+ @Override
+ public String format(java.util.logging.LogRecord record) {
+ return record.getLevel() + " - " + record.getMessage() + System.lineSeparator();
+ }
+ });
+ logger.addHandler(handler);
+ logger.setUseParentHandlers(false);
+ logger.setLevel(Level.ALL);
+ }
+ }
+
+ @Override
+ public void debug(String message) {
+ logger.log(Level.FINE, message);
+ }
+
+ @Override
+ public void info(String message) {
+ logger.log(Level.INFO, message);
+ }
+
+ @Override
+ public void warn(String message) {
+ logger.log(Level.WARNING, message);
+ }
+
+ @Override
+ public void error(String message) {
+ logger.log(Level.SEVERE, message);
+ }
+}
diff --git a/src/main/java/com/icepanel/core/DoubleSerializer.java b/src/main/java/com/icepanel/core/DoubleSerializer.java
new file mode 100644
index 0000000..658fa97
--- /dev/null
+++ b/src/main/java/com/icepanel/core/DoubleSerializer.java
@@ -0,0 +1,43 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+import java.io.IOException;
+
+/**
+ * Custom serializer that writes integer-valued doubles without a decimal point.
+ * For example, {@code 24000.0} is serialized as {@code 24000} instead of {@code 24000.0}.
+ * Non-integer values like {@code 3.14} are serialized normally.
+ */
+class DoubleSerializer extends JsonSerializer {
+ private static final SimpleModule MODULE;
+
+ static {
+ MODULE = new SimpleModule()
+ .addSerializer(Double.class, new DoubleSerializer())
+ .addSerializer(double.class, new DoubleSerializer());
+ }
+
+ /**
+ * Gets a module wrapping this serializer as an adapter for the Jackson ObjectMapper.
+ *
+ * @return A {@link SimpleModule} to be plugged onto Jackson ObjectMapper.
+ */
+ public static SimpleModule getModule() {
+ return MODULE;
+ }
+
+ @Override
+ public void serialize(Double value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
+ if (value != null && value == Math.floor(value) && !Double.isInfinite(value) && !Double.isNaN(value)) {
+ gen.writeNumber(value.longValue());
+ } else {
+ gen.writeNumber(value);
+ }
+ }
+}
diff --git a/src/main/java/com/icepanel/core/ILogger.java b/src/main/java/com/icepanel/core/ILogger.java
new file mode 100644
index 0000000..05378fb
--- /dev/null
+++ b/src/main/java/com/icepanel/core/ILogger.java
@@ -0,0 +1,38 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+/**
+ * Interface for custom logger implementations.
+ *
+ * Implement this interface to provide a custom logging backend for the SDK.
+ * The SDK will call the appropriate method based on the log level.
+ *
+ *
Example:
+ *
{@code
+ * public class MyCustomLogger implements ILogger {
+ * public void debug(String message) {
+ * System.out.println("[DBG] " + message);
+ * }
+ * public void info(String message) {
+ * System.out.println("[INF] " + message);
+ * }
+ * public void warn(String message) {
+ * System.out.println("[WRN] " + message);
+ * }
+ * public void error(String message) {
+ * System.out.println("[ERR] " + message);
+ * }
+ * }
+ * }
+ */
+public interface ILogger {
+ void debug(String message);
+
+ void info(String message);
+
+ void warn(String message);
+
+ void error(String message);
+}
diff --git a/src/main/java/com/icepanel/core/LogConfig.java b/src/main/java/com/icepanel/core/LogConfig.java
new file mode 100644
index 0000000..ef3e8b8
--- /dev/null
+++ b/src/main/java/com/icepanel/core/LogConfig.java
@@ -0,0 +1,98 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+/**
+ * Configuration for SDK logging.
+ *
+ * Use the builder to configure logging behavior:
+ *
{@code
+ * LogConfig config = LogConfig.builder()
+ * .level(LogLevel.DEBUG)
+ * .silent(false)
+ * .build();
+ * }
+ *
+ * Or with a custom logger:
+ *
{@code
+ * LogConfig config = LogConfig.builder()
+ * .level(LogLevel.DEBUG)
+ * .logger(new MyCustomLogger())
+ * .silent(false)
+ * .build();
+ * }
+ *
+ * Defaults:
+ *
+ * - {@code level} — {@link LogLevel#INFO}
+ * - {@code logger} — {@link ConsoleLogger} (writes to stderr via java.util.logging)
+ * - {@code silent} — {@code true} (no output unless explicitly enabled)
+ *
+ */
+public final class LogConfig {
+
+ private final LogLevel level;
+ private final ILogger logger;
+ private final boolean silent;
+
+ private LogConfig(LogLevel level, ILogger logger, boolean silent) {
+ this.level = level;
+ this.logger = logger;
+ this.silent = silent;
+ }
+
+ public LogLevel level() {
+ return level;
+ }
+
+ public ILogger logger() {
+ return logger;
+ }
+
+ public boolean silent() {
+ return silent;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static final class Builder {
+ private LogLevel level = LogLevel.INFO;
+ private ILogger logger = new ConsoleLogger();
+ private boolean silent = true;
+
+ private Builder() {}
+
+ /**
+ * Set the minimum log level. Only messages at this level or above will be logged.
+ * Defaults to {@link LogLevel#INFO}.
+ */
+ public Builder level(LogLevel level) {
+ this.level = level;
+ return this;
+ }
+
+ /**
+ * Set a custom logger implementation. Defaults to {@link ConsoleLogger}.
+ */
+ public Builder logger(ILogger logger) {
+ this.logger = logger;
+ return this;
+ }
+
+ /**
+ * Set whether logging is silent (disabled). Defaults to {@code true}.
+ * Set to {@code false} to enable log output.
+ */
+ public Builder silent(boolean silent) {
+ this.silent = silent;
+ return this;
+ }
+
+ public LogConfig build() {
+ return new LogConfig(level, logger, silent);
+ }
+ }
+}
diff --git a/src/main/java/com/icepanel/core/LogLevel.java b/src/main/java/com/icepanel/core/LogLevel.java
new file mode 100644
index 0000000..ab89ff6
--- /dev/null
+++ b/src/main/java/com/icepanel/core/LogLevel.java
@@ -0,0 +1,36 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+/**
+ * Log levels for SDK logging configuration.
+ * Silent by default — no log output unless explicitly configured.
+ */
+public enum LogLevel {
+ DEBUG(1),
+ INFO(2),
+ WARN(3),
+ ERROR(4);
+
+ private final int value;
+
+ LogLevel(int value) {
+ this.value = value;
+ }
+
+ public int getValue() {
+ return value;
+ }
+
+ /**
+ * Parse a log level from a string (case-insensitive).
+ *
+ * @param level the level string (debug, info, warn, error)
+ * @return the corresponding LogLevel
+ * @throws IllegalArgumentException if the string does not match any level
+ */
+ public static LogLevel fromString(String level) {
+ return LogLevel.valueOf(level.toUpperCase());
+ }
+}
diff --git a/src/main/java/com/icepanel/core/Logger.java b/src/main/java/com/icepanel/core/Logger.java
new file mode 100644
index 0000000..0f7df31
--- /dev/null
+++ b/src/main/java/com/icepanel/core/Logger.java
@@ -0,0 +1,97 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+/**
+ * SDK logger that filters messages based on level and silent mode.
+ *
+ * Silent by default — no log output unless explicitly configured.
+ * Create via {@link LogConfig} or directly:
+ *
{@code
+ * Logger logger = new Logger(LogLevel.DEBUG, new ConsoleLogger(), false);
+ * logger.debug("request sent");
+ * }
+ */
+public final class Logger {
+
+ private static final Logger DEFAULT = new Logger(LogLevel.INFO, new ConsoleLogger(), true);
+
+ private final LogLevel level;
+ private final ILogger logger;
+ private final boolean silent;
+
+ public Logger(LogLevel level, ILogger logger, boolean silent) {
+ this.level = level;
+ this.logger = logger;
+ this.silent = silent;
+ }
+
+ /**
+ * Returns a default silent logger (no output).
+ */
+ public static Logger getDefault() {
+ return DEFAULT;
+ }
+
+ /**
+ * Creates a Logger from a {@link LogConfig}. If config is {@code null}, returns the default silent logger.
+ */
+ public static Logger from(LogConfig config) {
+ if (config == null) {
+ return DEFAULT;
+ }
+ return new Logger(config.level(), config.logger(), config.silent());
+ }
+
+ /**
+ * Creates a Logger from an {@code Optional}. If empty, returns the default silent logger.
+ */
+ public static Logger from(java.util.Optional config) {
+ return config.map(Logger::from).orElse(DEFAULT);
+ }
+
+ private boolean shouldLog(LogLevel messageLevel) {
+ return !silent && level.getValue() <= messageLevel.getValue();
+ }
+
+ public boolean isDebug() {
+ return shouldLog(LogLevel.DEBUG);
+ }
+
+ public boolean isInfo() {
+ return shouldLog(LogLevel.INFO);
+ }
+
+ public boolean isWarn() {
+ return shouldLog(LogLevel.WARN);
+ }
+
+ public boolean isError() {
+ return shouldLog(LogLevel.ERROR);
+ }
+
+ public void debug(String message) {
+ if (isDebug()) {
+ logger.debug(message);
+ }
+ }
+
+ public void info(String message) {
+ if (isInfo()) {
+ logger.info(message);
+ }
+ }
+
+ public void warn(String message) {
+ if (isWarn()) {
+ logger.warn(message);
+ }
+ }
+
+ public void error(String message) {
+ if (isError()) {
+ logger.error(message);
+ }
+ }
+}
diff --git a/src/main/java/com/icepanel/core/LoggingInterceptor.java b/src/main/java/com/icepanel/core/LoggingInterceptor.java
new file mode 100644
index 0000000..91325c9
--- /dev/null
+++ b/src/main/java/com/icepanel/core/LoggingInterceptor.java
@@ -0,0 +1,104 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/**
+ * OkHttp interceptor that logs HTTP requests and responses.
+ *
+ * Logs request method, URL, and headers (with sensitive values redacted) at debug level.
+ * Logs response status at debug level, and 4xx/5xx responses at error level.
+ * Does nothing if the logger is silent.
+ */
+public final class LoggingInterceptor implements Interceptor {
+
+ private static final Set SENSITIVE_HEADERS = new HashSet<>(Arrays.asList(
+ "authorization",
+ "www-authenticate",
+ "x-api-key",
+ "api-key",
+ "apikey",
+ "x-api-token",
+ "x-auth-token",
+ "auth-token",
+ "proxy-authenticate",
+ "proxy-authorization",
+ "cookie",
+ "set-cookie",
+ "x-csrf-token",
+ "x-xsrf-token",
+ "x-session-token",
+ "x-access-token"));
+
+ private final Logger logger;
+
+ public LoggingInterceptor(Logger logger) {
+ this.logger = logger;
+ }
+
+ @Override
+ public Response intercept(Chain chain) throws IOException {
+ Request request = chain.request();
+
+ if (logger.isDebug()) {
+ StringBuilder sb = new StringBuilder();
+ sb.append("HTTP Request: ").append(request.method()).append(" ").append(request.url());
+ sb.append(" headers={");
+ boolean first = true;
+ for (String name : request.headers().names()) {
+ if (!first) {
+ sb.append(", ");
+ }
+ sb.append(name).append("=");
+ if (SENSITIVE_HEADERS.contains(name.toLowerCase())) {
+ sb.append("[REDACTED]");
+ } else {
+ sb.append(request.header(name));
+ }
+ first = false;
+ }
+ sb.append("}");
+ sb.append(" has_body=").append(request.body() != null);
+ logger.debug(sb.toString());
+ }
+
+ Response response = chain.proceed(request);
+
+ if (logger.isDebug()) {
+ StringBuilder sb = new StringBuilder();
+ sb.append("HTTP Response: status=").append(response.code());
+ sb.append(" url=").append(response.request().url());
+ sb.append(" headers={");
+ boolean first = true;
+ for (String name : response.headers().names()) {
+ if (!first) {
+ sb.append(", ");
+ }
+ sb.append(name).append("=");
+ if (SENSITIVE_HEADERS.contains(name.toLowerCase())) {
+ sb.append("[REDACTED]");
+ } else {
+ sb.append(response.header(name));
+ }
+ first = false;
+ }
+ sb.append("}");
+ logger.debug(sb.toString());
+ }
+
+ if (response.code() >= 400 && logger.isError()) {
+ logger.error("HTTP Error: status=" + response.code() + " url="
+ + response.request().url());
+ }
+
+ return response;
+ }
+}
diff --git a/src/main/java/com/icepanel/core/ObjectMappers.java b/src/main/java/com/icepanel/core/ObjectMappers.java
index b3f3433..cb86b3c 100644
--- a/src/main/java/com/icepanel/core/ObjectMappers.java
+++ b/src/main/java/com/icepanel/core/ObjectMappers.java
@@ -18,6 +18,7 @@ public final class ObjectMappers {
.addModule(new Jdk8Module())
.addModule(new JavaTimeModule())
.addModule(DateTimeDeserializer.getModule())
+ .addModule(DoubleSerializer.getModule())
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
.build();
diff --git a/src/main/java/com/icepanel/core/RetryInterceptor.java b/src/main/java/com/icepanel/core/RetryInterceptor.java
index 0c927da..cf11e54 100644
--- a/src/main/java/com/icepanel/core/RetryInterceptor.java
+++ b/src/main/java/com/icepanel/core/RetryInterceptor.java
@@ -19,11 +19,11 @@ public class RetryInterceptor implements Interceptor {
private static final Duration MAX_RETRY_DELAY = Duration.ofMillis(60000);
private static final double JITTER_FACTOR = 0.2;
- private final ExponentialBackoff backoff;
+ private final int maxRetries;
private final Random random = new Random();
public RetryInterceptor(int maxRetries) {
- this.backoff = new ExponentialBackoff(maxRetries);
+ this.maxRetries = maxRetries;
}
@Override
@@ -38,7 +38,8 @@ public Response intercept(Chain chain) throws IOException {
}
private Response retryChain(Response response, Chain chain) throws IOException {
- Optional nextBackoff = this.backoff.nextBackoff(response);
+ ExponentialBackoff backoff = new ExponentialBackoff(this.maxRetries);
+ Optional nextBackoff = backoff.nextBackoff(response);
while (nextBackoff.isPresent()) {
try {
Thread.sleep(nextBackoff.get().toMillis());
@@ -48,7 +49,7 @@ private Response retryChain(Response response, Chain chain) throws IOException {
response.close();
response = chain.proceed(chain.request());
if (shouldRetry(response.code())) {
- nextBackoff = this.backoff.nextBackoff(response);
+ nextBackoff = backoff.nextBackoff(response);
} else {
return response;
}
diff --git a/src/main/java/com/icepanel/core/Rfc2822DateTimeDeserializer.java b/src/main/java/com/icepanel/core/Rfc2822DateTimeDeserializer.java
new file mode 100644
index 0000000..630c254
--- /dev/null
+++ b/src/main/java/com/icepanel/core/Rfc2822DateTimeDeserializer.java
@@ -0,0 +1,25 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+import java.io.IOException;
+import java.time.OffsetDateTime;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+
+/**
+ * Custom deserializer that handles converting RFC 2822 (RFC 1123) dates into {@link OffsetDateTime} objects.
+ * This is used for fields with format "date-time-rfc-2822", such as Twilio's dateCreated, dateSent, dateUpdated.
+ */
+public class Rfc2822DateTimeDeserializer extends JsonDeserializer {
+
+ @Override
+ public OffsetDateTime deserialize(JsonParser parser, DeserializationContext context) throws IOException {
+ String raw = parser.getValueAsString();
+ return ZonedDateTime.parse(raw, DateTimeFormatter.RFC_1123_DATE_TIME).toOffsetDateTime();
+ }
+}
diff --git a/src/main/java/com/icepanel/core/SseEvent.java b/src/main/java/com/icepanel/core/SseEvent.java
new file mode 100644
index 0000000..9651098
--- /dev/null
+++ b/src/main/java/com/icepanel/core/SseEvent.java
@@ -0,0 +1,114 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Represents a Server-Sent Event with all standard fields.
+ * Used for event-level discrimination where the discriminator is at the SSE envelope level.
+ *
+ * @param The type of the data field
+ */
+@JsonInclude(JsonInclude.Include.NON_ABSENT)
+@JsonIgnoreProperties(ignoreUnknown = true)
+public final class SseEvent {
+ private final String event;
+ private final T data;
+ private final String id;
+ private final Long retry;
+
+ private SseEvent(String event, T data, String id, Long retry) {
+ this.event = event;
+ this.data = data;
+ this.id = id;
+ this.retry = retry;
+ }
+
+ @JsonProperty("event")
+ public Optional getEvent() {
+ return Optional.ofNullable(event);
+ }
+
+ @JsonProperty("data")
+ public T getData() {
+ return data;
+ }
+
+ @JsonProperty("id")
+ public Optional getId() {
+ return Optional.ofNullable(id);
+ }
+
+ @JsonProperty("retry")
+ public Optional getRetry() {
+ return Optional.ofNullable(retry);
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) return true;
+ if (o == null || getClass() != o.getClass()) return false;
+ SseEvent sseEvent = (SseEvent) o;
+ return Objects.equals(event, sseEvent.event)
+ && Objects.equals(data, sseEvent.data)
+ && Objects.equals(id, sseEvent.id)
+ && Objects.equals(retry, sseEvent.retry);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(event, data, id, retry);
+ }
+
+ @Override
+ public String toString() {
+ return "SseEvent{" + "event='"
+ + event + '\'' + ", data="
+ + data + ", id='"
+ + id + '\'' + ", retry="
+ + retry + '}';
+ }
+
+ public static Builder builder() {
+ return new Builder<>();
+ }
+
+ public static final class Builder {
+ private String event;
+ private T data;
+ private String id;
+ private Long retry;
+
+ private Builder() {}
+
+ public Builder event(String event) {
+ this.event = event;
+ return this;
+ }
+
+ public Builder data(T data) {
+ this.data = data;
+ return this;
+ }
+
+ public Builder id(String id) {
+ this.id = id;
+ return this;
+ }
+
+ public Builder retry(Long retry) {
+ this.retry = retry;
+ return this;
+ }
+
+ public SseEvent build() {
+ return new SseEvent<>(event, data, id, retry);
+ }
+ }
+}
diff --git a/src/main/java/com/icepanel/core/SseEventParser.java b/src/main/java/com/icepanel/core/SseEventParser.java
new file mode 100644
index 0000000..426e400
--- /dev/null
+++ b/src/main/java/com/icepanel/core/SseEventParser.java
@@ -0,0 +1,228 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.annotation.JsonTypeName;
+import com.fasterxml.jackson.core.type.TypeReference;
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * Utility class for parsing Server-Sent Events with support for discriminated unions.
+ *
+ * Handles two discrimination patterns:
+ *
+ * - Data-level discrimination: The discriminator (e.g., 'type') is inside the JSON data payload.
+ * Jackson's polymorphic deserialization handles this automatically.
+ * - Event-level discrimination: The discriminator (e.g., 'event') is at the SSE envelope level.
+ * This requires constructing the full SSE envelope for Jackson to process.
+ *
+ */
+public final class SseEventParser {
+
+ private static final Set SSE_ENVELOPE_FIELDS = new HashSet<>(Arrays.asList("event", "data", "id", "retry"));
+
+ private SseEventParser() {
+ // Utility class
+ }
+
+ /**
+ * Parse an SSE event using event-level discrimination.
+ *
+ * Constructs the full SSE envelope object with event, data, id, and retry fields,
+ * then deserializes it to the target union type.
+ *
+ * @param eventType The SSE event type (from event: field)
+ * @param data The SSE data content (from data: field)
+ * @param id The SSE event ID (from id: field), may be null
+ * @param retry The SSE retry value (from retry: field), may be null
+ * @param unionClass The target union class
+ * @param discriminatorProperty The property name used for discrimination (e.g., "event")
+ * @param The target type
+ * @return The deserialized object
+ */
+ public static T parseEventLevelUnion(
+ String eventType, String data, String id, Long retry, Class unionClass, String discriminatorProperty) {
+ try {
+ // Determine if data should be parsed as JSON based on the variant's expected type
+ Object parsedData = parseDataForVariant(eventType, data, unionClass, discriminatorProperty);
+
+ // Construct the SSE envelope object
+ Map envelope = new HashMap<>();
+ envelope.put(discriminatorProperty, eventType);
+ envelope.put("data", parsedData);
+ if (id != null) {
+ envelope.put("id", id);
+ }
+ if (retry != null) {
+ envelope.put("retry", retry);
+ }
+
+ // Serialize to JSON and deserialize to target type
+ String envelopeJson = ObjectMappers.JSON_MAPPER.writeValueAsString(envelope);
+ return ObjectMappers.JSON_MAPPER.readValue(envelopeJson, unionClass);
+ } catch (Exception e) {
+ throw new RuntimeException("Failed to parse SSE event with event-level discrimination", e);
+ }
+ }
+
+ /**
+ * Parse an SSE event using data-level discrimination.
+ *
+ * Simply parses the data field as JSON and deserializes it to the target type.
+ * Jackson's polymorphic deserialization handles the discrimination automatically.
+ *
+ * @param data The SSE data content (from data: field)
+ * @param valueType The target type
+ * @param The target type
+ * @return The deserialized object
+ */
+ public static T parseDataLevelUnion(String data, Class valueType) {
+ try {
+ return ObjectMappers.JSON_MAPPER.readValue(data, valueType);
+ } catch (Exception e) {
+ throw new RuntimeException("Failed to parse SSE data with data-level discrimination", e);
+ }
+ }
+
+ /**
+ * Determines if the given discriminator property indicates event-level discrimination.
+ * Event-level discrimination occurs when the discriminator is an SSE envelope field.
+ *
+ * @param discriminatorProperty The discriminator property name
+ * @return true if event-level discrimination, false otherwise
+ */
+ public static boolean isEventLevelDiscrimination(String discriminatorProperty) {
+ return SSE_ENVELOPE_FIELDS.contains(discriminatorProperty);
+ }
+
+ /**
+ * Attempts to find the discriminator property from the union class's Jackson annotations.
+ *
+ * @param unionClass The union class to inspect
+ * @return The discriminator property name, or empty if not found
+ */
+ public static Optional findDiscriminatorProperty(Class unionClass) {
+ try {
+ // Look for JsonTypeInfo on the class itself
+ JsonTypeInfo typeInfo = unionClass.getAnnotation(JsonTypeInfo.class);
+ if (typeInfo != null && !typeInfo.property().isEmpty()) {
+ return Optional.of(typeInfo.property());
+ }
+
+ // Look for inner Value interface with JsonTypeInfo
+ for (Class innerClass : unionClass.getDeclaredClasses()) {
+ typeInfo = innerClass.getAnnotation(JsonTypeInfo.class);
+ if (typeInfo != null && !typeInfo.property().isEmpty()) {
+ return Optional.of(typeInfo.property());
+ }
+ }
+ } catch (Exception e) {
+ // Ignore reflection errors
+ }
+ return Optional.empty();
+ }
+
+ /**
+ * Parse the data field based on what the matching variant expects.
+ * If the variant expects a String for its data field, returns the raw string.
+ * Otherwise, parses the data as JSON.
+ */
+ private static Object parseDataForVariant(
+ String eventType, String data, Class unionClass, String discriminatorProperty) {
+ if (data == null || data.isEmpty()) {
+ return data;
+ }
+
+ try {
+ // Try to find the variant class that matches this event type
+ Class variantClass = findVariantClass(unionClass, eventType, discriminatorProperty);
+ if (variantClass != null) {
+ // Check if the variant expects a String for the data field
+ Field dataField = findField(variantClass, "data");
+ if (dataField != null && String.class.equals(dataField.getType())) {
+ // Variant expects String - return raw data
+ return data;
+ }
+ }
+
+ // Try to parse as JSON
+ return ObjectMappers.JSON_MAPPER.readValue(data, new TypeReference>() {});
+ } catch (Exception e) {
+ // If JSON parsing fails, return as string
+ return data;
+ }
+ }
+
+ /**
+ * Find the variant class that matches the given discriminator value.
+ */
+ private static Class findVariantClass(
+ Class unionClass, String discriminatorValue, String discriminatorProperty) {
+ try {
+ // Look for JsonSubTypes annotation
+ JsonSubTypes subTypes = findJsonSubTypes(unionClass);
+ if (subTypes == null) {
+ return null;
+ }
+
+ for (JsonSubTypes.Type subType : subTypes.value()) {
+ JsonTypeName typeName = subType.value().getAnnotation(JsonTypeName.class);
+ if (typeName != null && typeName.value().equals(discriminatorValue)) {
+ return subType.value();
+ }
+ // Also check the name attribute of @JsonSubTypes.Type
+ if (subType.name().equals(discriminatorValue)) {
+ return subType.value();
+ }
+ }
+ } catch (Exception e) {
+ // Ignore reflection errors
+ }
+ return null;
+ }
+
+ /**
+ * Find JsonSubTypes annotation on the class or its inner classes.
+ */
+ private static JsonSubTypes findJsonSubTypes(Class unionClass) {
+ // Check the class itself
+ JsonSubTypes subTypes = unionClass.getAnnotation(JsonSubTypes.class);
+ if (subTypes != null) {
+ return subTypes;
+ }
+
+ // Check inner classes (for Fern-style unions with inner Value interface)
+ for (Class innerClass : unionClass.getDeclaredClasses()) {
+ subTypes = innerClass.getAnnotation(JsonSubTypes.class);
+ if (subTypes != null) {
+ return subTypes;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Find a field by name in a class, including private fields.
+ */
+ private static Field findField(Class clazz, String fieldName) {
+ try {
+ return clazz.getDeclaredField(fieldName);
+ } catch (NoSuchFieldException e) {
+ // Check superclass
+ Class superClass = clazz.getSuperclass();
+ if (superClass != null && superClass != Object.class) {
+ return findField(superClass, fieldName);
+ }
+ return null;
+ }
+ }
+}
diff --git a/src/main/java/com/icepanel/core/Stream.java b/src/main/java/com/icepanel/core/Stream.java
index 1c7bc11..7a7ec71 100644
--- a/src/main/java/com/icepanel/core/Stream.java
+++ b/src/main/java/com/icepanel/core/Stream.java
@@ -28,7 +28,8 @@ public final class Stream implements Iterable, Closeable {
public enum StreamType {
JSON,
- SSE
+ SSE,
+ SSE_EVENT_DISCRIMINATED
}
private final Class valueType;
@@ -37,6 +38,7 @@ public enum StreamType {
private final String messageTerminator;
private final String streamTerminator;
private final Reader sseReader;
+ private final String discriminatorProperty;
private boolean isClosed = false;
/**
@@ -53,11 +55,18 @@ public Stream(Class valueType, Reader reader, String delimiter) {
this.messageTerminator = delimiter;
this.streamTerminator = null;
this.sseReader = null;
+ this.discriminatorProperty = null;
}
private Stream(Class valueType, StreamType type, Reader reader, String terminator) {
+ this(valueType, type, reader, terminator, null);
+ }
+
+ private Stream(
+ Class valueType, StreamType type, Reader reader, String terminator, String discriminatorProperty) {
this.valueType = valueType;
this.streamType = type;
+ this.discriminatorProperty = discriminatorProperty;
if (type == StreamType.JSON) {
this.scanner = new Scanner(reader).useDelimiter(terminator);
this.messageTerminator = terminator;
@@ -87,6 +96,38 @@ public static Stream fromSse(Class valueType, Reader sseReader, String
return new Stream<>(valueType, StreamType.SSE, sseReader, streamTerminator);
}
+ /**
+ * Creates a stream from SSE data with event-level discrimination support.
+ * Use this when the SSE payload is a discriminated union where the discriminator
+ * is an SSE envelope field (e.g., 'event').
+ *
+ * @param valueType The class of the objects in the stream.
+ * @param sseReader The reader that provides the SSE data.
+ * @param discriminatorProperty The property name used for discrimination (e.g., "event").
+ * @param The type of objects in the stream.
+ * @return A new Stream instance configured for SSE with event-level discrimination.
+ */
+ public static Stream fromSseWithEventDiscrimination(
+ Class valueType, Reader sseReader, String discriminatorProperty) {
+ return new Stream<>(valueType, StreamType.SSE_EVENT_DISCRIMINATED, sseReader, null, discriminatorProperty);
+ }
+
+ /**
+ * Creates a stream from SSE data with event-level discrimination support and a stream terminator.
+ *
+ * @param valueType The class of the objects in the stream.
+ * @param sseReader The reader that provides the SSE data.
+ * @param discriminatorProperty The property name used for discrimination (e.g., "event").
+ * @param streamTerminator The terminator string that signals end of stream (e.g., "[DONE]").
+ * @param The type of objects in the stream.
+ * @return A new Stream instance configured for SSE with event-level discrimination.
+ */
+ public static Stream fromSseWithEventDiscrimination(
+ Class valueType, Reader sseReader, String discriminatorProperty, String streamTerminator) {
+ return new Stream<>(
+ valueType, StreamType.SSE_EVENT_DISCRIMINATED, sseReader, streamTerminator, discriminatorProperty);
+ }
+
@Override
public void close() throws IOException {
if (!isClosed) {
@@ -112,10 +153,14 @@ private boolean isStreamClosed() {
*/
@Override
public Iterator iterator() {
- if (streamType == StreamType.SSE) {
- return new SSEIterator();
- } else {
- return new JsonIterator();
+ switch (streamType) {
+ case SSE:
+ return new SSEIterator();
+ case SSE_EVENT_DISCRIMINATED:
+ return new SSEEventDiscriminatedIterator();
+ case JSON:
+ default:
+ return new JsonIterator();
}
}
@@ -299,4 +344,170 @@ private boolean readNextMessage() {
}
}
}
+
+ /**
+ * Iterator for SSE streams with event-level discrimination.
+ * Uses SseEventParser to construct the full SSE envelope for Jackson deserialization.
+ */
+ private final class SSEEventDiscriminatedIterator implements Iterator {
+ private Scanner sseScanner;
+ private T nextItem;
+ private boolean hasNextItem = false;
+ private boolean endOfStream = false;
+ private StringBuilder eventDataBuffer = new StringBuilder();
+ private String currentEventType = null;
+ private String currentEventId = null;
+ private Long currentRetry = null;
+
+ private SSEEventDiscriminatedIterator() {
+ if (sseReader != null && !isStreamClosed()) {
+ this.sseScanner = new Scanner(sseReader);
+ } else {
+ this.endOfStream = true;
+ }
+ }
+
+ @Override
+ public boolean hasNext() {
+ if (isStreamClosed() || endOfStream) {
+ return false;
+ }
+
+ if (hasNextItem) {
+ return true;
+ }
+
+ return readNextMessage();
+ }
+
+ @Override
+ public T next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException("No more elements in stream");
+ }
+
+ T result = nextItem;
+ nextItem = null;
+ hasNextItem = false;
+ return result;
+ }
+
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+ private boolean readNextMessage() {
+ if (sseScanner == null || isStreamClosed()) {
+ endOfStream = true;
+ return false;
+ }
+
+ try {
+ while (sseScanner.hasNextLine()) {
+ String line = sseScanner.nextLine();
+
+ if (line.trim().isEmpty()) {
+ if (eventDataBuffer.length() > 0 || currentEventType != null) {
+ try {
+ // Use SseEventParser for event-level discrimination
+ nextItem = SseEventParser.parseEventLevelUnion(
+ currentEventType,
+ eventDataBuffer.toString(),
+ currentEventId,
+ currentRetry,
+ valueType,
+ discriminatorProperty);
+ hasNextItem = true;
+ resetEventState();
+ return true;
+ } catch (Exception parseEx) {
+ System.err.println("Failed to parse SSE event: " + parseEx.getMessage());
+ resetEventState();
+ continue;
+ }
+ }
+ continue;
+ }
+
+ if (line.startsWith(DATA_PREFIX)) {
+ String dataContent = line.substring(DATA_PREFIX.length());
+ if (dataContent.startsWith(" ")) {
+ dataContent = dataContent.substring(1);
+ }
+
+ if (eventDataBuffer.length() == 0
+ && streamTerminator != null
+ && dataContent.trim().equals(streamTerminator)) {
+ endOfStream = true;
+ return false;
+ }
+
+ if (eventDataBuffer.length() > 0) {
+ eventDataBuffer.append('\n');
+ }
+ eventDataBuffer.append(dataContent);
+ } else if (line.startsWith("event:")) {
+ String eventValue = line.length() > 6 ? line.substring(6) : "";
+ if (eventValue.startsWith(" ")) {
+ eventValue = eventValue.substring(1);
+ }
+ currentEventType = eventValue;
+ } else if (line.startsWith("id:")) {
+ String idValue = line.length() > 3 ? line.substring(3) : "";
+ if (idValue.startsWith(" ")) {
+ idValue = idValue.substring(1);
+ }
+ currentEventId = idValue;
+ } else if (line.startsWith("retry:")) {
+ String retryValue = line.length() > 6 ? line.substring(6) : "";
+ if (retryValue.startsWith(" ")) {
+ retryValue = retryValue.substring(1);
+ }
+ try {
+ currentRetry = Long.parseLong(retryValue.trim());
+ } catch (NumberFormatException e) {
+ // Ignore invalid retry values
+ }
+ } else if (line.startsWith(":")) {
+ // Comment line (ignored)
+ }
+ }
+
+ // Handle any remaining buffered data at end of stream
+ if (eventDataBuffer.length() > 0 || currentEventType != null) {
+ try {
+ nextItem = SseEventParser.parseEventLevelUnion(
+ currentEventType,
+ eventDataBuffer.toString(),
+ currentEventId,
+ currentRetry,
+ valueType,
+ discriminatorProperty);
+ hasNextItem = true;
+ resetEventState();
+ return true;
+ } catch (Exception parseEx) {
+ System.err.println("Failed to parse final SSE event: " + parseEx.getMessage());
+ resetEventState();
+ }
+ }
+
+ endOfStream = true;
+ return false;
+
+ } catch (Exception e) {
+ System.err.println("Failed to parse SSE stream: " + e.getMessage());
+ endOfStream = true;
+ return false;
+ }
+ }
+
+ private void resetEventState() {
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ currentEventId = null;
+ currentRetry = null;
+ }
+ }
}
diff --git a/src/main/java/com/icepanel/core/SyncPage.java b/src/main/java/com/icepanel/core/SyncPage.java
new file mode 100644
index 0000000..e137dc7
--- /dev/null
+++ b/src/main/java/com/icepanel/core/SyncPage.java
@@ -0,0 +1,24 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.icepanel.core;
+
+import java.util.List;
+import java.util.NoSuchElementException;
+import java.util.function.Supplier;
+
+public class SyncPage extends BasePage