feat: implement polls predictions helix eventsub public beta (#326)

* feat: implement polls predictions helix eventsub public beta

* refactor: reorder prediction color enum to align with chat badge

* feat: add tests for polls predictions (de)serialization

* docs: clarify required args for get polls and get predictions

* feat: add eventsub polls predictions deserialization tests

* refactor: allow singular builder for poll choices and prediction outcomes

common/src/main/java/com/github/twitch4j/common/annotation/Unofficial.java

@@ -6,6 +6,8 @@
 
 /**
  * Annotates a method or features that uses unofficial api endpoints, those can break at any point in time. Use at your own risk.
+ * <p>
+ * All aspects of this functionality including query parameters and response structure are subject to change without notice.
  */
 @Documented
 @Retention(RetentionPolicy.SOURCE)

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPollBeginCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPollBeginCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPollEndCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPollEndCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPollProgressCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPollProgressCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPredictionBeginCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPredictionBeginCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPredictionEndCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPredictionEndCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPredictionLockCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPredictionLockCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/condition/ChannelPredictionProgressCondition.java

@@ -0,0 +1,12 @@
+package com.github.twitch4j.eventsub.condition;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import lombok.experimental.SuperBuilder;
+import lombok.extern.jackson.Jacksonized;
+
+@SuperBuilder
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Jacksonized
+public class ChannelPredictionProgressCondition extends ChannelEventSubCondition {}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/BitsVoting.java

@@ -0,0 +1,27 @@
+package com.github.twitch4j.eventsub.domain;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AccessLevel;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+@Data
+@Setter(AccessLevel.PRIVATE)
+@NoArgsConstructor
+public class BitsVoting {
+
+    /**
+     * Indicates if Bits can be used for voting.
+     */
+    @Accessors(fluent = true)
+    @JsonProperty("is_enabled")
+    private Boolean isEnabled;
+
+    /**
+     * Number of Bits required to vote once with Bits.
+     */
+    private Integer amountPerVote;
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/ChannelPointsVoting.java

@@ -0,0 +1,27 @@
+package com.github.twitch4j.eventsub.domain;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AccessLevel;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+@Data
+@Setter(AccessLevel.PRIVATE)
+@NoArgsConstructor
+public class ChannelPointsVoting {
+
+    /**
+     * Indicates if Channel Points can be used for voting.
+     */
+    @Accessors(fluent = true)
+    @JsonProperty("is_enabled")
+    private Boolean isEnabled;
+
+    /**
+     * Number of Channel Points required to vote once with Channel Points.
+     */
+    private Integer amountPerVote;
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/PollChoice.java

@@ -0,0 +1,52 @@
+package com.github.twitch4j.eventsub.domain;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.With;
+import lombok.extern.jackson.Jacksonized;
+import org.jetbrains.annotations.Nullable;
+
+@With
+@Data
+@Setter(AccessLevel.PRIVATE)
+@Builder(toBuilder = true)
+@Jacksonized
+@NoArgsConstructor
+@AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class PollChoice {
+
+    /**
+     * ID for the choice.
+     */
+    private String id;
+
+    /**
+     * Text displayed for the choice. Maximum: 25 characters.
+     */
+    private String title;
+
+    /**
+     * Total number of votes received for the choice across all methods of voting.
+     */
+    @Nullable
+    private Integer votes;
+
+    /**
+     * Number of votes received via Channel Points.
+     */
+    @Nullable
+    private Integer channelPointsVotes;
+
+    /**
+     * Number of votes received via Bits.
+     */
+    @Nullable
+    private Integer bitsVotes;
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/PollStatus.java

@@ -0,0 +1,38 @@
+package com.github.twitch4j.eventsub.domain;
+
+import com.fasterxml.jackson.annotation.JsonEnumDefaultValue;
+
+public enum PollStatus {
+
+    /**
+     * Poll is currently in progress.
+     */
+    ACTIVE,
+
+    /**
+     * Poll has reached its ended_at time.
+     */
+    COMPLETED,
+
+    /**
+     * Poll has been manually terminated before its ended_at time, but still visible.
+     */
+    TERMINATED,
+
+    /**
+     * Poll is no longer visible on the channel.
+     */
+    ARCHIVED,
+
+    /**
+     * Poll is no longer visible to any user on Twitch.
+     */
+    MODERATED,
+
+    /**
+     * Something went wrong determining the state.
+     */
+    @JsonEnumDefaultValue
+    INVALID
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/PredictionColor.java

@@ -0,0 +1,5 @@
+package com.github.twitch4j.eventsub.domain;
+
+public enum PredictionColor {
+    BLUE, PINK
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/PredictionOutcome.java

@@ -0,0 +1,57 @@
+package com.github.twitch4j.eventsub.domain;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.With;
+import lombok.extern.jackson.Jacksonized;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.List;
+
+@With
+@Data
+@Setter(AccessLevel.PRIVATE)
+@Builder(toBuilder = true)
+@Jacksonized
+@NoArgsConstructor
+@AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class PredictionOutcome {
+
+    /**
+     * The outcome ID.
+     */
+    private String id;
+
+    /**
+     * The outcome title. Maximum: 25 characters.
+     */
+    private String title;
+
+    /**
+     * The color for the outcome.
+     */
+    private PredictionColor color;
+
+    /**
+     * The number of users who used Channel Points on this outcome.
+     */
+    private Integer users;
+
+    /**
+     * The total number of Channel Points used on this outcome.
+     */
+    private Long channelPoints;
+
+    /**
+     * The users who used the most Channel Points on this outcome.
+     */
+    @Nullable
+    private List<Predictor> topPredictors;
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/PredictionStatus.java

@@ -0,0 +1,25 @@
+package com.github.twitch4j.eventsub.domain;
+
+public enum PredictionStatus {
+
+    /**
+     * A winning outcome has been chosen and the Channel Points have been distributed to the users who guessed the correct outcome.
+     */
+    RESOLVED,
+
+    /**
+     * The Prediction is active and viewers can make predictions.
+     */
+    ACTIVE,
+
+    /**
+     * The Prediction has been canceled and the Channel Points have been refunded to participants.
+     */
+    CANCELED,
+
+    /**
+     * The Prediction has been locked and viewers can no longer make predictions.
+     */
+    LOCKED
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/domain/Predictor.java

@@ -0,0 +1,43 @@
+package com.github.twitch4j.eventsub.domain;
+
+import lombok.AccessLevel;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import org.jetbrains.annotations.Nullable;
+
+@Data
+@Setter(AccessLevel.PRIVATE)
+@NoArgsConstructor
+public class Predictor {
+
+    /**
+     * The ID of the user.
+     */
+    private String userId;
+
+    /**
+     * The login name of the user.
+     */
+    private String userLogin;
+
+    /**
+     * The display name of the user.
+     */
+    private String userName;
+
+    /**
+     * The number of Channel Points won.
+     * <p>
+     * This value is always null in the event payload for Prediction progress and Prediction lock.
+     * This value is 0 if the outcome did not win or if the Prediction was canceled and Channel Points were refunded.
+     */
+    @Nullable
+    private Integer channelPointsWon;
+
+    /**
+     * The number of Channel Points used to participate in the Prediction.
+     */
+    private Integer channelPointsUsed;
+
+}

eventsub-common/src/main/java/com/github/twitch4j/eventsub/events/ChannelPollBeginEvent.java

@@ -0,0 +1,8 @@
+package com.github.twitch4j.eventsub.events;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+
+@ToString(callSuper = true)
+@EqualsAndHashCode(callSuper = true)
+public class ChannelPollBeginEvent extends ChannelPollEvent {}