add allChildren and getNextPage functions (#299)

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next release
+
+- Adds `allChildren` function in User service to get a paginated list of child users
+- Adds `getNextPage` function in User service to get next paginated list of child users
+
 ## v7.0.1 (2023-12-08)
 
 - Adds the `object` field to all models; previously, most models were missing this field.

src/main/java/com/easypost/model/ChildUserCollection.java

@@ -0,0 +1,25 @@
+package com.easypost.model;
+
+import java.util.List;
+import java.util.Map;
+
+import lombok.Getter;
+
+@Getter
+public final class ChildUserCollection extends PaginatedCollection<User> {
+    private List<User> children;
+
+    @Override
+    protected Map<String, Object> buildNextPageParameters(List<User> children, Integer pageSize) {
+        String lastId = children.get(children.size() - 1).getId();
+
+        Map<String, Object> parameters = new java.util.HashMap<>();
+        parameters.put("before_id", lastId);
+
+        if (pageSize != null) {
+            parameters.put("page_size", pageSize);
+        }
+
+        return parameters;
+    }
+}

src/main/java/com/easypost/service/UserService.java

@@ -2,18 +2,23 @@
 
 import com.easypost.Constants;
 import com.easypost.exception.EasyPostException;
+import com.easypost.exception.General.EndOfPaginationError;
 import com.easypost.exception.General.FilteringError;
 import com.easypost.http.Requestor;
 import com.easypost.http.Requestor.RequestMethod;
 import com.easypost.model.ApiKey;
 import com.easypost.model.ApiKeys;
 import com.easypost.model.Brand;
+import com.easypost.model.ChildUserCollection;
 import com.easypost.model.User;
 
+import lombok.SneakyThrows;
+
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.function.Function;
 
 public class UserService {
     private final EasyPostClient client;
@@ -137,4 +142,35 @@ public Brand updateBrand(final String id, final Map<String, Object> params) thro
 
         return Requestor.request(RequestMethod.PUT, endpoint, wrappedParams, Brand.class, client);
     }
+
+    /**
+     * Retrieve the paginated list of child users for the authenticated user.
+     *
+     * @param params Map of parameters.
+     * @return ChildUserCollection object.
+     * @throws EasyPostException when the request fails.
+     */
+    public ChildUserCollection allChildren(final Map<String, Object> params) throws EasyPostException {
+        String endpoint = "users/children";
+
+        return Requestor.request(RequestMethod.GET, endpoint, params, ChildUserCollection.class, client);
+    }
+
+    /**
+     * Get the next page of a ChildUserCollection.
+     *
+     * @param collection ChildUserCollection to get next page of.
+     * @param pageSize   The number of results to return on the next page.
+     * @return ChildUserCollection object.
+     * @throws EndOfPaginationError when there are no more pages to retrieve.
+     */
+    public ChildUserCollection getNextPage(ChildUserCollection collection, Integer pageSize)
+        throws EndOfPaginationError {
+        return collection.getNextPage(new Function<Map<String, Object>, ChildUserCollection>() {
+            @Override @SneakyThrows
+            public ChildUserCollection apply(Map<String, Object> parameters) {
+                return allChildren(parameters);
+            }
+        }, collection.getChildren(), pageSize);
+    }
 }

src/test/java/com/easypost/UserTest.java

@@ -1,19 +1,25 @@
 package com.easypost;
 
 import com.easypost.exception.EasyPostException;
+import com.easypost.exception.General.EndOfPaginationError;
 import com.easypost.model.Brand;
+import com.easypost.model.ChildUserCollection;
 import com.easypost.model.User;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
 
 public final class UserTest {
     private static String testUserId = null;
@@ -177,4 +183,54 @@ public void testUpdateBrand() throws EasyPostException {
         assertTrue(brand.getId().startsWith("brd_"));
         assertEquals(color, brand.getColor());
     }
+
+    /**
+     * Test retrieving a paginated list of children.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testAllChildren() throws EasyPostException {
+        vcr.setUpTest("all_children");
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("page_size", Fixtures.pageSize());
+
+        ChildUserCollection children = vcr.client.user.allChildren(params);
+
+        List<User> childrenList = children.getChildren();
+
+        assertTrue(childrenList.size() <= Fixtures.pageSize());
+        assertNotNull(children.getHasMore());
+        assertTrue(childrenList.stream().allMatch(children_user -> children_user != null));
+    }
+
+    /**
+     * Test retrieving the next page of child users.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testGetNextPage() throws EasyPostException {
+        vcr.setUpTest("get_next_page");
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("page_size", Fixtures.pageSize());
+        ChildUserCollection collection = vcr.client.user.allChildren(params);
+
+        try {
+            ChildUserCollection nextPage = vcr.client.user.getNextPage(collection, Fixtures.pageSize());
+
+            assertNotNull(nextPage);
+
+            String firstIdOfFirstPage = collection.getChildren().get(0).getId();
+            String firstIdOfSecondPage = nextPage.getChildren().get(0).getId();
+
+            assertNotEquals(firstIdOfFirstPage, firstIdOfSecondPage);
+        } catch (EndOfPaginationError e) { // There's no next page, that's not a failure
+            assertTrue(true);
+        } catch (Exception e) { // Any other exception is a failure
+            fail();
+        }
+    }
 }