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/newscatcher/api/core/LoggingInterceptor.java b/src/main/java/com/newscatcher/api/core/LoggingInterceptor.java
new file mode 100644
index 0000000..7568199
--- /dev/null
+++ b/src/main/java/com/newscatcher/api/core/LoggingInterceptor.java
@@ -0,0 +1,104 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.newscatcher.api.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/newscatcher/api/core/NewscatcherApiApiException.java b/src/main/java/com/newscatcher/api/core/NewscatcherApiApiException.java
index 5aea8cc..58ad4a3 100644
--- a/src/main/java/com/newscatcher/api/core/NewscatcherApiApiException.java
+++ b/src/main/java/com/newscatcher/api/core/NewscatcherApiApiException.java
@@ -65,9 +65,9 @@ public Map> headers() {
return this.headers;
}
- @java.lang.Override
+ @Override
public String toString() {
return "NewscatcherApiApiException{" + "message: " + getMessage() + ", statusCode: " + statusCode + ", body: "
- + body + "}";
+ + ObjectMappers.stringify(body) + "}";
}
}
diff --git a/src/main/java/com/newscatcher/api/core/NullableNonemptyFilter.java b/src/main/java/com/newscatcher/api/core/NullableNonemptyFilter.java
index fe77d6f..8f70f6e 100644
--- a/src/main/java/com/newscatcher/api/core/NullableNonemptyFilter.java
+++ b/src/main/java/com/newscatcher/api/core/NullableNonemptyFilter.java
@@ -14,6 +14,9 @@ public boolean equals(Object o) {
}
private boolean isOptionalEmpty(Object o) {
- return o instanceof Optional && !((Optional) o).isPresent();
+ if (o instanceof Optional) {
+ return !((Optional) o).isPresent();
+ }
+ return false;
}
}
diff --git a/src/main/java/com/newscatcher/api/core/ObjectMappers.java b/src/main/java/com/newscatcher/api/core/ObjectMappers.java
index cb2c72f..8e78be8 100644
--- a/src/main/java/com/newscatcher/api/core/ObjectMappers.java
+++ b/src/main/java/com/newscatcher/api/core/ObjectMappers.java
@@ -4,6 +4,7 @@
package com.newscatcher.api.core;
import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
@@ -33,4 +34,12 @@ public static String stringify(Object o) {
return o.getClass().getName() + "@" + Integer.toHexString(o.hashCode());
}
}
+
+ public static Object parseErrorBody(String responseBodyString) {
+ try {
+ return JSON_MAPPER.readValue(responseBodyString, Object.class);
+ } catch (JsonProcessingException ignored) {
+ return responseBodyString;
+ }
+ }
}
diff --git a/src/main/java/com/newscatcher/api/core/RequestOptions.java b/src/main/java/com/newscatcher/api/core/RequestOptions.java
index dd39cdf..a6cb9f7 100644
--- a/src/main/java/com/newscatcher/api/core/RequestOptions.java
+++ b/src/main/java/com/newscatcher/api/core/RequestOptions.java
@@ -20,17 +20,25 @@ public final class RequestOptions {
private final Map> headerSuppliers;
+ private final Map queryParameters;
+
+ private final Map> queryParameterSuppliers;
+
private RequestOptions(
String apiKey,
Optional timeout,
TimeUnit timeoutTimeUnit,
Map headers,
- Map> headerSuppliers) {
+ Map> headerSuppliers,
+ Map queryParameters,
+ Map> queryParameterSuppliers) {
this.apiKey = apiKey;
this.timeout = timeout;
this.timeoutTimeUnit = timeoutTimeUnit;
this.headers = headers;
this.headerSuppliers = headerSuppliers;
+ this.queryParameters = queryParameters;
+ this.queryParameterSuppliers = queryParameterSuppliers;
}
public Optional getTimeout() {
@@ -53,6 +61,14 @@ public Map getHeaders() {
return headers;
}
+ public Map getQueryParameters() {
+ Map queryParameters = new HashMap<>(this.queryParameters);
+ this.queryParameterSuppliers.forEach((key, supplier) -> {
+ queryParameters.put(key, supplier.get());
+ });
+ return queryParameters;
+ }
+
public static Builder builder() {
return new Builder();
}
@@ -68,6 +84,10 @@ public static class Builder {
private final Map> headerSuppliers = new HashMap<>();
+ private final Map queryParameters = new HashMap<>();
+
+ private final Map> queryParameterSuppliers = new HashMap<>();
+
public Builder apiKey(String apiKey) {
this.apiKey = apiKey;
return this;
@@ -94,8 +114,25 @@ public Builder addHeader(String key, Supplier value) {
return this;
}
+ public Builder addQueryParameter(String key, String value) {
+ this.queryParameters.put(key, value);
+ return this;
+ }
+
+ public Builder addQueryParameter(String key, Supplier value) {
+ this.queryParameterSuppliers.put(key, value);
+ return this;
+ }
+
public RequestOptions build() {
- return new RequestOptions(apiKey, timeout, timeoutTimeUnit, headers, headerSuppliers);
+ return new RequestOptions(
+ apiKey,
+ timeout,
+ timeoutTimeUnit,
+ headers,
+ headerSuppliers,
+ queryParameters,
+ queryParameterSuppliers);
}
}
}
diff --git a/src/main/java/com/newscatcher/api/core/RetryInterceptor.java b/src/main/java/com/newscatcher/api/core/RetryInterceptor.java
index d084037..265fe1f 100644
--- a/src/main/java/com/newscatcher/api/core/RetryInterceptor.java
+++ b/src/main/java/com/newscatcher/api/core/RetryInterceptor.java
@@ -5,6 +5,9 @@
import java.io.IOException;
import java.time.Duration;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
import java.util.Optional;
import java.util.Random;
import okhttp3.Interceptor;
@@ -12,7 +15,10 @@
public class RetryInterceptor implements Interceptor {
- private static final Duration ONE_SECOND = Duration.ofSeconds(1);
+ private static final Duration INITIAL_RETRY_DELAY = Duration.ofMillis(1000);
+ private static final Duration MAX_RETRY_DELAY = Duration.ofMillis(60000);
+ private static final double JITTER_FACTOR = 0.2;
+
private final ExponentialBackoff backoff;
private final Random random = new Random();
@@ -32,7 +38,7 @@ public Response intercept(Chain chain) throws IOException {
}
private Response retryChain(Response response, Chain chain) throws IOException {
- Optional nextBackoff = this.backoff.nextBackoff();
+ Optional nextBackoff = this.backoff.nextBackoff(response);
while (nextBackoff.isPresent()) {
try {
Thread.sleep(nextBackoff.get().toMillis());
@@ -42,7 +48,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();
+ nextBackoff = this.backoff.nextBackoff(response);
} else {
return response;
}
@@ -51,6 +57,102 @@ private Response retryChain(Response response, Chain chain) throws IOException {
return response;
}
+ /**
+ * Calculates the retry delay from response headers, with fallback to exponential backoff.
+ * Priority: Retry-After > X-RateLimit-Reset > Exponential Backoff
+ */
+ private Duration getRetryDelayFromHeaders(Response response, int retryAttempt) {
+ // Check for Retry-After header first (RFC 7231), with no jitter
+ String retryAfter = response.header("Retry-After");
+ if (retryAfter != null) {
+ // Parse as number of seconds...
+ Optional secondsDelay = tryParseLong(retryAfter)
+ .map(seconds -> seconds * 1000)
+ .filter(delayMs -> delayMs > 0)
+ .map(delayMs -> Math.min(delayMs, MAX_RETRY_DELAY.toMillis()))
+ .map(Duration::ofMillis);
+ if (secondsDelay.isPresent()) {
+ return secondsDelay.get();
+ }
+
+ // ...or as an HTTP date; both are valid
+ Optional dateDelay = tryParseHttpDate(retryAfter)
+ .map(resetTime -> resetTime.toInstant().toEpochMilli() - System.currentTimeMillis())
+ .filter(delayMs -> delayMs > 0)
+ .map(delayMs -> Math.min(delayMs, MAX_RETRY_DELAY.toMillis()))
+ .map(Duration::ofMillis);
+ if (dateDelay.isPresent()) {
+ return dateDelay.get();
+ }
+ }
+
+ // Then check for industry-standard X-RateLimit-Reset header, with positive jitter
+ String rateLimitReset = response.header("X-RateLimit-Reset");
+ if (rateLimitReset != null) {
+ // Assume Unix timestamp in epoch seconds
+ Optional rateLimitDelay = tryParseLong(rateLimitReset)
+ .map(resetTimeSeconds -> (resetTimeSeconds * 1000) - System.currentTimeMillis())
+ .filter(delayMs -> delayMs > 0)
+ .map(delayMs -> Math.min(delayMs, MAX_RETRY_DELAY.toMillis()))
+ .map(this::addPositiveJitter)
+ .map(Duration::ofMillis);
+ if (rateLimitDelay.isPresent()) {
+ return rateLimitDelay.get();
+ }
+ }
+
+ // Fall back to exponential backoff, with symmetric jitter
+ long baseDelay = INITIAL_RETRY_DELAY.toMillis() * (1L << retryAttempt); // 2^retryAttempt
+ long cappedDelay = Math.min(baseDelay, MAX_RETRY_DELAY.toMillis());
+ return Duration.ofMillis(addSymmetricJitter(cappedDelay));
+ }
+
+ /**
+ * Attempts to parse a string as a long, returning empty Optional on failure.
+ */
+ private Optional tryParseLong(String value) {
+ if (value == null) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.of(Long.parseLong(value));
+ } catch (NumberFormatException e) {
+ return Optional.empty();
+ }
+ }
+
+ /**
+ * Attempts to parse a string as an HTTP date (RFC 1123), returning empty Optional on failure.
+ */
+ private Optional tryParseHttpDate(String value) {
+ if (value == null) {
+ return Optional.empty();
+ }
+ try {
+ return Optional.of(ZonedDateTime.parse(value, DateTimeFormatter.RFC_1123_DATE_TIME));
+ } catch (DateTimeParseException e) {
+ return Optional.empty();
+ }
+ }
+
+ /**
+ * Adds positive jitter (100-120% of original value) to prevent thundering herd.
+ * Used for X-RateLimit-Reset header delays.
+ */
+ private long addPositiveJitter(long delayMs) {
+ double jitterMultiplier = 1.0 + (random.nextDouble() * JITTER_FACTOR);
+ return (long) (delayMs * jitterMultiplier);
+ }
+
+ /**
+ * Adds symmetric jitter (90-110% of original value) to prevent thundering herd.
+ * Used for exponential backoff delays.
+ */
+ private long addSymmetricJitter(long delayMs) {
+ double jitterMultiplier = 1.0 + ((random.nextDouble() - 0.5) * JITTER_FACTOR);
+ return (long) (delayMs * jitterMultiplier);
+ }
+
private static boolean shouldRetry(int statusCode) {
return statusCode == 408 || statusCode == 429 || statusCode >= 500;
}
@@ -65,14 +167,14 @@ private final class ExponentialBackoff {
this.maxNumRetries = maxNumRetries;
}
- public Optional nextBackoff() {
- retryNumber += 1;
- if (retryNumber > maxNumRetries) {
+ public Optional nextBackoff(Response response) {
+ if (retryNumber >= maxNumRetries) {
return Optional.empty();
}
- int upperBound = (int) Math.pow(2, retryNumber);
- return Optional.of(ONE_SECOND.multipliedBy(random.nextInt(upperBound)));
+ Duration delay = getRetryDelayFromHeaders(response, retryNumber);
+ retryNumber += 1;
+ return Optional.of(delay);
}
}
}
diff --git a/src/main/java/com/newscatcher/api/core/Rfc2822DateTimeDeserializer.java b/src/main/java/com/newscatcher/api/core/Rfc2822DateTimeDeserializer.java
new file mode 100644
index 0000000..345f71c
--- /dev/null
+++ b/src/main/java/com/newscatcher/api/core/Rfc2822DateTimeDeserializer.java
@@ -0,0 +1,25 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.newscatcher.api.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/newscatcher/api/core/SseEvent.java b/src/main/java/com/newscatcher/api/core/SseEvent.java
new file mode 100644
index 0000000..28cbcc2
--- /dev/null
+++ b/src/main/java/com/newscatcher/api/core/SseEvent.java
@@ -0,0 +1,114 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.newscatcher.api.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/newscatcher/api/core/SseEventParser.java b/src/main/java/com/newscatcher/api/core/SseEventParser.java
new file mode 100644
index 0000000..da2e974
--- /dev/null
+++ b/src/main/java/com/newscatcher/api/core/SseEventParser.java
@@ -0,0 +1,228 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+package com.newscatcher.api.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/newscatcher/api/core/Stream.java b/src/main/java/com/newscatcher/api/core/Stream.java
index ce28044..b3b525c 100644
--- a/src/main/java/com/newscatcher/api/core/Stream.java
+++ b/src/main/java/com/newscatcher/api/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();
}
}
@@ -174,8 +219,8 @@ private final class SSEIterator implements Iterator {
private T nextItem;
private boolean hasNextItem = false;
private boolean endOfStream = false;
- private StringBuilder buffer = new StringBuilder();
- private boolean prefixSeen = false;
+ private StringBuilder eventDataBuffer = new StringBuilder();
+ private String currentEventType = null;
private SSEIterator() {
if (sseReader != null && !isStreamClosed()) {
@@ -223,39 +268,228 @@ private boolean readNextMessage() {
try {
while (sseScanner.hasNextLine()) {
- String chunk = sseScanner.nextLine();
- buffer.append(chunk).append(NEWLINE);
+ String line = sseScanner.nextLine();
+
+ if (line.trim().isEmpty()) {
+ if (eventDataBuffer.length() > 0) {
+ try {
+ nextItem = ObjectMappers.JSON_MAPPER.readValue(eventDataBuffer.toString(), valueType);
+ hasNextItem = true;
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ return true;
+ } catch (Exception parseEx) {
+ System.err.println("Failed to parse SSE event: " + parseEx.getMessage());
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ continue;
+ }
+ }
+ continue;
+ }
- int terminatorIndex;
- while ((terminatorIndex = buffer.indexOf(messageTerminator)) >= 0) {
- String line = buffer.substring(0, terminatorIndex + messageTerminator.length());
- buffer.delete(0, terminatorIndex + messageTerminator.length());
+ if (line.startsWith(DATA_PREFIX)) {
+ String dataContent = line.substring(DATA_PREFIX.length());
+ if (dataContent.startsWith(" ")) {
+ dataContent = dataContent.substring(1);
+ }
- line = line.trim();
- if (line.isEmpty()) {
- continue;
+ if (eventDataBuffer.length() == 0
+ && streamTerminator != null
+ && dataContent.trim().equals(streamTerminator)) {
+ endOfStream = true;
+ return false;
}
- if (!prefixSeen && line.startsWith(DATA_PREFIX)) {
- prefixSeen = true;
- line = line.substring(DATA_PREFIX.length()).trim();
- } else if (!prefixSeen) {
- continue;
+ 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:")) {
+ // Event ID field (ignored)
+ } else if (line.startsWith("retry:")) {
+ // Retry field (ignored)
+ } else if (line.startsWith(":")) {
+ // Comment line (ignored)
+ }
+ }
+
+ if (eventDataBuffer.length() > 0) {
+ try {
+ nextItem = ObjectMappers.JSON_MAPPER.readValue(eventDataBuffer.toString(), valueType);
+ hasNextItem = true;
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ return true;
+ } catch (Exception parseEx) {
+ System.err.println("Failed to parse final SSE event: " + parseEx.getMessage());
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ }
+ }
- if (streamTerminator != null && line.contains(streamTerminator)) {
+ endOfStream = true;
+ return false;
+
+ } catch (Exception e) {
+ System.err.println("Failed to parse SSE stream: " + e.getMessage());
+ endOfStream = true;
+ return false;
+ }
+ }
+ }
+
+ /**
+ * 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 {
- nextItem = ObjectMappers.JSON_MAPPER.readValue(line, valueType);
- hasNextItem = true;
- prefixSeen = false;
- return true;
- } catch (Exception parseEx) {
- continue;
+ 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();
}
}
@@ -268,5 +502,12 @@ private boolean readNextMessage() {
return false;
}
}
+
+ private void resetEventState() {
+ eventDataBuffer.setLength(0);
+ currentEventType = null;
+ currentEventId = null;
+ currentRetry = null;
+ }
}
}
diff --git a/src/main/java/com/newscatcher/api/resources/aggregation/requests/AggregationGetRequest.java b/src/main/java/com/newscatcher/api/resources/aggregation/requests/AggregationGetRequest.java
deleted file mode 100644
index 9a28606..0000000
--- a/src/main/java/com/newscatcher/api/resources/aggregation/requests/AggregationGetRequest.java
+++ /dev/null
@@ -1,2501 +0,0 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
-package com.newscatcher.api.resources.aggregation.requests;
-
-import com.fasterxml.jackson.annotation.JsonAnyGetter;
-import com.fasterxml.jackson.annotation.JsonAnySetter;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonSetter;
-import com.fasterxml.jackson.annotation.Nulls;
-import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
-import com.newscatcher.api.core.ObjectMappers;
-import com.newscatcher.api.resources.aggregation.types.AggregationGetRequestPublishedDatePrecision;
-import com.newscatcher.api.resources.aggregation.types.AggregationGetRequestSortBy;
-import com.newscatcher.api.types.AggregationBy;
-import java.time.OffsetDateTime;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.Objects;
-import java.util.Optional;
-import org.jetbrains.annotations.NotNull;
-
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonDeserialize(builder = AggregationGetRequest.Builder.class)
-public final class AggregationGetRequest {
- private final String q;
-
- private final Optional aggregationBy;
-
- private final Optional searchIn;
-
- private final Optional predefinedSources;
-
- private final Optional sources;
-
- private final Optional notSources;
-
- private final Optional lang;
-
- private final Optional notLang;
-
- private final Optional countries;
-
- private final Optional notCountries;
-
- private final Optional notAuthorName;
-
- private final Optional from;
-
- private final Optional to;
-
- private final Optional publishedDatePrecision;
-
- private final Optional byParseDate;
-
- private final Optional sortBy;
-
- private final Optional rankedOnly;
-
- private final Optional fromRank;
-
- private final Optional toRank;
-
- private final Optional isHeadline;
-
- private final Optional isOpinion;
-
- private final Optional isPaidContent;
-
- private final Optional parentUrl;
-
- private final Optional allLinks;
-
- private final Optional allDomainLinks;
-
- private final Optional wordCountMin;
-
- private final Optional wordCountMax;
-
- private final Optional page;
-
- private final Optional pageSize;
-
- private final Optional includeNlpData;
-
- private final Optional hasNlp;
-
- private final Optional theme;
-
- private final Optional notTheme;
-
- private final Optional orgEntityName;
-
- private final Optional perEntityName;
-
- private final Optional locEntityName;
-
- private final Optional miscEntityName;
-
- private final Optional titleSentimentMin;
-
- private final Optional titleSentimentMax;
-
- private final Optional contentSentimentMin;
-
- private final Optional contentSentimentMax;
-
- private final Optional iptcTags;
-
- private final Optional notIptcTags;
-
- private final Optional robotsCompliant;
-
- private final Map additionalProperties;
-
- private AggregationGetRequest(
- String q,
- Optional aggregationBy,
- Optional searchIn,
- Optional predefinedSources,
- Optional sources,
- Optional notSources,
- Optional lang,
- Optional notLang,
- Optional countries,
- Optional notCountries,
- Optional notAuthorName,
- Optional from,
- Optional to,
- Optional publishedDatePrecision,
- Optional byParseDate,
- Optional sortBy,
- Optional rankedOnly,
- Optional fromRank,
- Optional toRank,
- Optional isHeadline,
- Optional isOpinion,
- Optional isPaidContent,
- Optional parentUrl,
- Optional allLinks,
- Optional allDomainLinks,
- Optional wordCountMin,
- Optional wordCountMax,
- Optional page,
- Optional pageSize,
- Optional includeNlpData,
- Optional hasNlp,
- Optional theme,
- Optional notTheme,
- Optional orgEntityName,
- Optional perEntityName,
- Optional locEntityName,
- Optional miscEntityName,
- Optional titleSentimentMin,
- Optional titleSentimentMax,
- Optional contentSentimentMin,
- Optional contentSentimentMax,
- Optional iptcTags,
- Optional notIptcTags,
- Optional robotsCompliant,
- Map additionalProperties) {
- this.q = q;
- this.aggregationBy = aggregationBy;
- this.searchIn = searchIn;
- this.predefinedSources = predefinedSources;
- this.sources = sources;
- this.notSources = notSources;
- this.lang = lang;
- this.notLang = notLang;
- this.countries = countries;
- this.notCountries = notCountries;
- this.notAuthorName = notAuthorName;
- this.from = from;
- this.to = to;
- this.publishedDatePrecision = publishedDatePrecision;
- this.byParseDate = byParseDate;
- this.sortBy = sortBy;
- this.rankedOnly = rankedOnly;
- this.fromRank = fromRank;
- this.toRank = toRank;
- this.isHeadline = isHeadline;
- this.isOpinion = isOpinion;
- this.isPaidContent = isPaidContent;
- this.parentUrl = parentUrl;
- this.allLinks = allLinks;
- this.allDomainLinks = allDomainLinks;
- this.wordCountMin = wordCountMin;
- this.wordCountMax = wordCountMax;
- this.page = page;
- this.pageSize = pageSize;
- this.includeNlpData = includeNlpData;
- this.hasNlp = hasNlp;
- this.theme = theme;
- this.notTheme = notTheme;
- this.orgEntityName = orgEntityName;
- this.perEntityName = perEntityName;
- this.locEntityName = locEntityName;
- this.miscEntityName = miscEntityName;
- this.titleSentimentMin = titleSentimentMin;
- this.titleSentimentMax = titleSentimentMax;
- this.contentSentimentMin = contentSentimentMin;
- this.contentSentimentMax = contentSentimentMax;
- this.iptcTags = iptcTags;
- this.notIptcTags = notIptcTags;
- this.robotsCompliant = robotsCompliant;
- this.additionalProperties = additionalProperties;
- }
-
- /**
- * @return The keyword(s) to search for in articles. Query syntax supports logical operators (AND, OR, NOT) and wildcards:
- *
- * - For an exact match, use double quotes. For example,
"technology news".
- * - Use
* to search for any keyword.
- * - Use
+ to include and - to exclude specific words or phrases.
- * For example, +Apple, -Google.
- * - Use
AND, OR, and NOT to refine search results.
- * For example, technology AND (Apple OR Microsoft) NOT Google.
- *
- * For more details, see Advanced querying.
- */
- @JsonProperty("q")
- public String getQ() {
- return q;
- }
-
- @JsonProperty("aggregation_by")
- public Optional getAggregationBy() {
- return aggregationBy;
- }
-
- @JsonProperty("search_in")
- public Optional getSearchIn() {
- return searchIn;
- }
-
- /**
- * @return Predefined top news sources per country.
- * Format: start with the word top, followed by the number of desired sources, and then the two-letter country code ISO 3166-1 alpha-2. Multiple countries with the number of top sources can be specified as a comma-separated string.
- * Examples:
- *
- * "top 100 US""top 33 AT""top 50 US, top 20 GB""top 33 AT, top 50 IT"
- */
- @JsonProperty("predefined_sources")
- public Optional getPredefinedSources() {
- return predefinedSources;
- }
-
- /**
- * @return One or more news sources to narrow down the search. The format must be a domain URL. Subdomains, such as finance.yahoo.com, are also acceptable.To specify multiple sources, use a comma-separated string.
- * Examples:
- *
- * "nytimes.com""theguardian.com, finance.yahoo.com"
- */
- @JsonProperty("sources")
- public Optional getSources() {
- return sources;
- }
-
- /**
- * @return The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string.
- * Example: "cnn.com, wsj.com"
- */
- @JsonProperty("not_sources")
- public Optional getNotSources() {
- return notSources;
- }
-
- /**
- * @return The language(s) of the search. The only accepted format is the two-letter ISO 639-1 code. To select multiple languages, use a comma-separated string.
- * Example: "en, es"
- * To learn more, see Enumerated parameters > Language.
- */
- @JsonProperty("lang")
- public Optional getLang() {
- return lang;
- }
-
- /**
- * @return The language(s) to exclude from the search. The accepted format is the two-letter ISO 639-1 code. To exclude multiple languages, use a comma-separated string.
- * Example: "fr, de"
- * To learn more, see Enumerated parameters > Language.
- */
- @JsonProperty("not_lang")
- public Optional getNotLang() {
- return notLang;
- }
-
- /**
- * @return The countries where the news publisher is located. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To select multiple countries, use a comma-separated string.
- * Example: "US, CA"
- * To learn more, see Enumerated parameters > Country.
- */
- @JsonProperty("countries")
- public Optional getCountries() {
- return countries;
- }
-
- /**
- * @return The publisher location countries to exclude from the search. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To exclude multiple countries, use a comma-separated string.
- * Example:"US, CA"
- * To learn more, see Enumerated parameters > Country.
- */
- @JsonProperty("not_countries")
- public Optional getNotCountries() {
- return notCountries;
- }
-
- /**
- * @return The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string.
- * Example: "John Doe, Jane Doe"
- */
- @JsonProperty("not_author_name")
- public Optional getNotAuthorName() {
- return notAuthorName;
- }
-
- /**
- * @return The starting point in time to search from. Accepts date-time strings in ISO 8601 format and plain text. The default time zone is UTC.
- * Formats with examples:
- *
- * - YYYY-mm-ddTHH:MM:SS:
2024-07-01T00:00:00
- * - YYYY-MM-dd:
2024-07-01
- * - YYYY/mm/dd HH:MM:SS:
2024/07/01 00:00:00
- * - YYYY/mm/dd:
2024/07/01
- * - English phrases:
7 day ago, today
- *
- * Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.
- */
- @JsonProperty("from_")
- public Optional getFrom() {
- return from;
- }
-
- /**
- * @return The ending point in time to search up to. Accepts date-time strings in ISO 8601 format and plain text. The default time zone is UTC.
- * Formats with examples:
- *
- * - YYYY-mm-ddTHH:MM:SS:
2024-07-01T00:00:00
- * - YYYY-MM-dd:
2024-07-01
- * - YYYY/mm/dd HH:MM:SS:
2024/07/01 00:00:00
- * - YYYY/mm/dd:
2024/07/01
- * - English phrases:
1 day ago, now
- *
- * Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.
- */
- @JsonProperty("to_")
- public Optional getTo() {
- return to;
- }
-
- /**
- * @return The precision of the published date. There are three types:
- *
- * full: The day and time of an article is correctly identified with the appropriate timezone.timezone unknown: The day and time of an article is correctly identified without timezone.date: Only the day is identified without an exact time.
- */
- @JsonProperty("published_date_precision")
- public Optional getPublishedDatePrecision() {
- return publishedDatePrecision;
- }
-
- /**
- * @return If true, the from_ and to_ parameters use article parse dates instead of published dates. Additionally, the parse_date variable is added to the output for each article object.
- */
- @JsonProperty("by_parse_date")
- public Optional getByParseDate() {
- return byParseDate;
- }
-
- /**
- * @return The sorting order of the results. Possible values are:
- *
- * relevancy: The most relevant results first.date: The most recently published results first.rank: The results from the highest-ranked sources first.
- */
- @JsonProperty("sort_by")
- public Optional getSortBy() {
- return sortBy;
- }
-
- /**
- * @return If true, limits the search to sources ranked in the top 1 million online websites. If false, includes unranked sources which are assigned a rank of 999999.
- */
- @JsonProperty("ranked_only")
- public Optional getRankedOnly() {
- return rankedOnly;
- }
-
- /**
- * @return The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
- */
- @JsonProperty("from_rank")
- public Optional getFromRank() {
- return fromRank;
- }
-
- /**
- * @return The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
- */
- @JsonProperty("to_rank")
- public Optional getToRank() {
- return toRank;
- }
-
- /**
- * @return If true, only returns articles that were posted on the home page of a given news domain.
- */
- @JsonProperty("is_headline")
- public Optional getIsHeadline() {
- return isHeadline;
- }
-
- /**
- * @return If true, returns only opinion pieces. If false, excludes opinion-based articles and returns news only.
- */
- @JsonProperty("is_opinion")
- public Optional getIsOpinion() {
- return isOpinion;
- }
-
- /**
- * @return If false, returns only articles that have publicly available complete content. Some publishers partially block content, so this setting ensures that only full articles are retrieved.
- */
- @JsonProperty("is_paid_content")
- public Optional getIsPaidContent() {
- return isPaidContent;
- }
-
- /**
- * @return The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string.
- * Example: "wsj.com/politics, wsj.com/tech"
- */
- @JsonProperty("parent_url")
- public Optional getParentUrl() {
- return parentUrl;
- }
-
- /**
- * @return The complete URL(s) mentioned in the article. For multiple URLs, use a comma-separated string.
- * Example: "https://aiindex.stanford.edu/report, https://www.stateof.ai"
- * For more details, see Search by URL.
- */
- @JsonProperty("all_links")
- public Optional getAllLinks() {
- return allLinks;
- }
-
- /**
- * @return The domain(s) mentioned in the article. For multiple domains, use a comma-separated string.
- * Example: "who.int, nih.gov"
- * For more details, see Search by URL.
- */
- @JsonProperty("all_domain_links")
- public Optional getAllDomainLinks() {
- return allDomainLinks;
- }
-
- /**
- * @return The minimum number of words an article must contain. To be used for avoiding articles with small content.
- */
- @JsonProperty("word_count_min")
- public Optional getWordCountMin() {
- return wordCountMin;
- }
-
- /**
- * @return The maximum number of words an article can contain. To be used for avoiding articles with large content.
- */
- @JsonProperty("word_count_max")
- public Optional getWordCountMax() {
- return wordCountMax;
- }
-
- /**
- * @return The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles.
- * For details, see How to paginate large datasets.
- */
- @JsonProperty("page")
- public Optional getPage() {
- return page;
- }
-
- /**
- * @return The number of articles to return per page.
- */
- @JsonProperty("page_size")
- public Optional getPageSize() {
- return pageSize;
- }
-
- @JsonProperty("include_nlp_data")
- public Optional getIncludeNlpData() {
- return includeNlpData;
- }
-
- @JsonProperty("has_nlp")
- public Optional getHasNlp() {
- return hasNlp;
- }
-
- /**
- * @return Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string.
- * Example: "Finance, Tech"
- * Note: The theme parameter is only available if NLP is included in your subscription plan.
- * To learn more, see NLP features.
- * Available options: Business, Economics, Entertainment, Finance, Health, Politics, Science, Sports, Tech, Crime, Financial Crime, Lifestyle, Automotive, Travel, Weather, General.
- */
- @JsonProperty("theme")
- public Optional getTheme() {
- return theme;
- }
-
- /**
- * @return Inverse of the theme parameter. Excludes articles based on their general topic, as determined by NLP analysis. To exclude multiple themes, use a comma-separated string.
- * Example: "Crime, Tech"
- * Note: The not_theme parameter is only available if NLP is included in your subscription plan.
- * To learn more, see NLP features.
- */
- @JsonProperty("not_theme")
- public Optional getNotTheme() {
- return notTheme;
- }
-
- /**
- * @return Filters articles that mention specific organization names, as identified by NLP analysis. To specify multiple organizations, use a comma-separated string. To search named entities in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).
- * Example: "Apple, Microsoft"
- * Note: The ORG_entity_name parameter is only available if NLP is included in your subscription plan.
- * To learn more, see Search by entity.
- */
- @JsonProperty("ORG_entity_name")
- public Optional getOrgEntityName() {
- return orgEntityName;
- }
-
- /**
- * @return Filters articles that mention specific person names, as identified by NLP analysis. To specify multiple names, use a comma-separated string. To search named entities in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).
- * Example: "Elon Musk, Jeff Bezos"
- * Note: The PER_entity_name parameter is only available if NLP is included in your subscription plan.
- * To learn more, see Search by entity.
- */
- @JsonProperty("PER_entity_name")
- public Optional getPerEntityName() {
- return perEntityName;
- }
-
- /**
- * @return Filters articles that mention specific location names, as identified by NLP analysis. To specify multiple locations, use a comma-separated string. To search named entities in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).
- * Example: "California, New York"
- * Note: The LOC_entity_name parameter is only available if NLP is included in your subscription plan.
- * To learn more, see Search by entity.
- */
- @JsonProperty("LOC_entity_name")
- public Optional getLocEntityName() {
- return locEntityName;
- }
-
- /**
- * @return Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more. To specify multiple entities, use a comma-separated string. To search named entities in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).
- * Example: "Bitcoin, Blockchain"
- * Note: The MISC_entity_name parameter is only available if NLP is included in your subscription plan.
- * To learn more, see Search by entity.
- */
- @JsonProperty("MISC_entity_name")
- public Optional getMiscEntityName() {
- return miscEntityName;
- }
-
- /**
- * @return Filters articles based on the minimum sentiment score of their titles.
- * Range is -1.0 to 1.0, where:
- *
- * - Negative values indicate negative sentiment.
- * - Positive values indicate positive sentiment.
- * - Values close to 0 indicate neutral sentiment.
- *
- * Note: The title_sentiment_min parameter is only available if NLP is included in your subscription plan.
- * To learn more, see NLP features.
- */
- @JsonProperty("title_sentiment_min")
- public Optional getTitleSentimentMin() {
- return titleSentimentMin;
- }
-
- /**
- * @return Filters articles based on the maximum sentiment score of their titles.
- * Range is -1.0 to 1.0, where:
- *
- * - Negative values indicate negative sentiment.
- * - Positive values indicate positive sentiment.
- * - Values close to 0 indicate neutral sentiment.
- *
- * Note: The title_sentiment_max parameter is only available if NLP is included in your subscription plan.
- * To learn more, see NLP features.
- */
- @JsonProperty("title_sentiment_max")
- public Optional getTitleSentimentMax() {
- return titleSentimentMax;
- }
-
- /**
- * @return Filters articles based on the minimum sentiment score of their content.
- * Range is