Trakt API updates

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Next release
 
+* Address [Trakt requiring pagination](https://github.com/trakt/trakt-api/discussions/681) for lists and library
+  (formerly collection) endpoints:
+  * Add paginated variants of `Sync.collectionMovies()`, `Sync.collectionShows()`, `Users.collectionMovies()`
+    and `Users.collectionShows()` with required `page` and `limit` parameters. The original methods are deprecated.
+  * Add `Users.listItems()` variants that require pagination and support type and sort order parameters. The original
+    method is deprecated.
+* Add history endpoints to `Sync`. Thanks @defhead! [#125](https://github.com/UweTrottmann/trakt-java/pull/125)
+* Add `Sync.playback()` that also accepts start and end times and supports pagination. The existing `getPlayback()`
+  methods are deprecated.
+* Add warnings to `watched_at` fields
+  that [Trakt will only store and return minute-precision timestamps](https://github.com/trakt/trakt-api/discussions/694).
+* Add `TraktV2.isAccountLimitExceeded()`, `TraktV2.isRateLimitExceeded()` and `TraktV2.isServerError()` methods to help
+  inspect `Response` objects for more common Trakt HTTP status codes.
+* Add variants of the watchlist methods that support pagination and sort order parameters.
+
 ## 6.16.0 - 2024-11-07
 
 * `TraktV2`: add `isUnauthorized(response)`, `isAccountLocked(response)` and `isNotVip(response)` helper methods.

RELEASING.md

@@ -2,8 +2,14 @@
 
 ## Local testing
 
+Note: on Windows, avoid Git Bash. It uses its own `gpg`.
+
 ```bash
-./mwnw clean install -P release,heyuwe-sign
+./mvnw clean install -P release,heyuwe-sign -DskipTests
+```
+
+```powershell
+.\mvnw.cmd clean install -P release,heyuwe-sign -DskipTests
 ```
 
 ## Preparing a release and deploying it to Maven Central

pom.xml

@@ -132,8 +132,7 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.14.1</version>
                 <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
+                    <release>8</release>
                 </configuration>
             </plugin>
             <!-- https://github.com/apache/maven-release/releases -->
@@ -205,6 +204,8 @@
                         <version>3.12.0</version>
                         <configuration>
                             <source>8</source>
+                            <!-- Disable checks for missing Javadoc comments -->
+                            <doclint>all,-missing</doclint>
                         </configuration>
                         <executions>
                             <execution>

src/main/java/com/uwetrottmann/trakt5/TraktV2.java

@@ -361,6 +361,14 @@ public static boolean isUnauthorized(Response<?> response) {
         return response.code() == 401;
     }
 
+    /**
+     * Checks if the response code is 420, which indicates an account limit would be exceeded. These limits <a
+     * href="https://trakt.docs.apiary.io/#introduction/vip-methods">can be higher for VIP users</a>.
+     */
+    public static boolean isAccountLimitExceeded(Response<?> response) {
+        return response.code() == 420;
+    }
+
     /**
      * Checks if the response code is 423, which indicates the
      * <a href="https://trakt.docs.apiary.io/#introduction/locked-user-account">Trakt account is locked</a>.
@@ -377,6 +385,21 @@ public static boolean isNotVip(Response<?> response) {
         return response.code() == 426;
     }
 
+    /**
+     * Checks if the response code is 429, which indicates the rate limit was exceeded.
+     * <a href="https://trakt.docs.apiary.io/#introduction/rate-limiting">Trakt rate limiting info</a>
+     */
+    public static boolean isRateLimitExceeded(Response<?> response) {
+        return response.code() == 429;
+    }
+
+    /**
+     * Checks if the response code is 500 or greater, which indicates a server error.
+     */
+    public static boolean isServerError(Response<?> response) {
+        return response.code() >= 500;
+    }
+
     /**
      * If it exists, returns the value of the {@code X-Pagination-Page-Count} header from the response.
      */

src/main/java/com/uwetrottmann/trakt5/entities/BaseCheckinResponse.java

@@ -21,6 +21,10 @@
 
 public abstract class BaseCheckinResponse {
 
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero.
+     */
     public OffsetDateTime watched_at;
     public ShareSettings sharing;
 

src/main/java/com/uwetrottmann/trakt5/entities/BaseEpisode.java

@@ -26,6 +26,10 @@ public class BaseEpisode {
     public OffsetDateTime collected_at;
     /** watched */
     public Integer plays;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero.
+     */
     public OffsetDateTime last_watched_at;
     /** progress */
     public Boolean completed;

src/main/java/com/uwetrottmann/trakt5/entities/BaseMovie.java

@@ -23,6 +23,10 @@ public class BaseMovie {
     public Movie movie;
 
     public OffsetDateTime collected_at;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero.
+     */
     public OffsetDateTime last_watched_at;
     public OffsetDateTime last_updated_at;
     public OffsetDateTime listed_at;

src/main/java/com/uwetrottmann/trakt5/entities/BaseShow.java

@@ -33,6 +33,10 @@ public class BaseShow {
     public OffsetDateTime listed_at;
     /** watched */
     public Integer plays;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero.
+     */
     public OffsetDateTime last_watched_at;
     public OffsetDateTime last_updated_at;
     public OffsetDateTime reset_at;

src/main/java/com/uwetrottmann/trakt5/entities/HistoryEntry.java

@@ -21,6 +21,10 @@
 public class HistoryEntry {
 
     public Long id;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero.
+     */
     public OffsetDateTime watched_at;
     public String action;
     public String type;

src/main/java/com/uwetrottmann/trakt5/entities/SyncEpisode.java

@@ -34,6 +34,10 @@ public class SyncEpisode {
     public EpisodeIds ids;
 
     public OffsetDateTime collected_at;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero. Using {@code .truncatedTo(ChronoUnit.MINUTES)} can be helpful.
+     */
     public OffsetDateTime watched_at;
     public OffsetDateTime rated_at;
     public Rating rating;

src/main/java/com/uwetrottmann/trakt5/entities/SyncMovie.java

@@ -32,6 +32,10 @@ public class SyncMovie {
     public MovieIds ids;
 
     public OffsetDateTime collected_at;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero. Using {@code .truncatedTo(ChronoUnit.MINUTES)} can be helpful.
+     */
     public OffsetDateTime watched_at;
     public OffsetDateTime rated_at;
     public Rating rating;

src/main/java/com/uwetrottmann/trakt5/entities/SyncSeason.java

@@ -29,6 +29,10 @@ public class SyncSeason {
     public List<SyncEpisode> episodes;
 
     public OffsetDateTime collected_at;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero. Using {@code .truncatedTo(ChronoUnit.MINUTES)} can be helpful.
+     */
     public OffsetDateTime watched_at;
     public OffsetDateTime rated_at;
     public Rating rating;

src/main/java/com/uwetrottmann/trakt5/entities/SyncShow.java

@@ -29,6 +29,10 @@ public class SyncShow {
     public List<SyncSeason> seasons;
 
     public OffsetDateTime collected_at;
+    /**
+     * Warning: Trakt is planning to only store and return minute-precision timestamps for watched_at. So seconds and
+     * nanoseconds will always be zero. Using {@code .truncatedTo(ChronoUnit.MINUTES)} can be helpful.
+     */
     public OffsetDateTime watched_at;
     public OffsetDateTime rated_at;
     public Rating rating;

src/main/java/com/uwetrottmann/trakt5/enums/PlaybackType.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright © 2026 Uwe Trottmann <uwe@uwetrottmann.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.uwetrottmann.trakt5.enums;
+
+public enum PlaybackType implements TraktEnum {
+
+    MOVIES("movies"),
+    EPISODES("episodes");
+
+    private final String value;
+
+    PlaybackType(String value) {
+        this.value = value;
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+
+}

src/main/java/com/uwetrottmann/trakt5/services/Calendars.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.services;
 
+import com.uwetrottmann.trakt5.TraktV2;
 import com.uwetrottmann.trakt5.entities.CalendarMovieEntry;
 import com.uwetrottmann.trakt5.entities.CalendarShowEntry;
 import retrofit2.Call;
@@ -27,7 +28,7 @@
 public interface Calendars {
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      *
      * @see #shows(String, int)
      */
@@ -38,7 +39,7 @@ Call<List<CalendarShowEntry>> myShows(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      *
      * @see #newShows(String, int)
      */
@@ -49,7 +50,7 @@ Call<List<CalendarShowEntry>> myNewShows(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      *
      * @see #seasonPremieres(String, int)
      */
@@ -60,7 +61,7 @@ Call<List<CalendarShowEntry>> mySeasonPremieres(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      *
      * @see #movies(String, int)
      */

src/main/java/com/uwetrottmann/trakt5/services/Checkin.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.services;
 
+import com.uwetrottmann.trakt5.TraktV2;
 import com.uwetrottmann.trakt5.entities.EpisodeCheckin;
 import com.uwetrottmann.trakt5.entities.EpisodeCheckinResponse;
 import com.uwetrottmann.trakt5.entities.MovieCheckin;
@@ -28,7 +29,7 @@
 public interface Checkin {
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Check into an episode. This should be tied to a user action to manually indicate they are watching something. The
      * item will display as watching on the site, then automatically switch to watched status once the duration has
@@ -40,7 +41,7 @@ Call<EpisodeCheckinResponse> checkin(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Check into a movie. This should be tied to a user action to manually indicate they are watching something. The
      * item will display as watching on the site, then automatically switch to watched status once the duration has
@@ -52,7 +53,7 @@ Call<MovieCheckinResponse> checkin(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Removes any active checkins, no need to provide a specific item.
      */

src/main/java/com/uwetrottmann/trakt5/services/Comments.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.services;
 
+import com.uwetrottmann.trakt5.TraktV2;
 import com.uwetrottmann.trakt5.entities.Comment;
 import retrofit2.Call;
 import retrofit2.http.Body;
@@ -30,7 +31,7 @@
 public interface Comments {
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Add a new comment to a movie, show, episode, or list. If you add a review, it needs to be at least 200 words.
      * Also make sure to allow and encourage spoilers to be indicated in your app.
@@ -44,7 +45,7 @@ Call<Comment> post(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Returns a single comment and indicates how many replies it has. Use GET /comments/:id/replies to get the actual
      * replies.
@@ -57,7 +58,7 @@ Call<Comment> get(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Update a single comment created within the last hour. The OAuth user must match the author of the comment in
      * order to update it.
@@ -72,7 +73,7 @@ Call<Comment> update(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Delete a single comment created within the last hour. This also effectively removes any replies this comment has.
      * The OAuth user must match the author of the comment in order to delete it.
@@ -85,7 +86,7 @@ Call<Void> delete(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Returns all replies for a comment. It is possible these replies could have replies themselves, so in that case
      * you would just call GET /comment/:id/replies again with the new comment_id.
@@ -98,7 +99,7 @@ Call<List<Comment>> replies(
     );
 
     /**
-     * <b>OAuth Required</b>
+     * <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
      * <p>
      * Add a new reply to an existing comment. Also make sure to allow and encourage spoilers to be indicated in your
      * app.