Support get follower IDs api (#682)

Close #621

Author: imasahiro

line-bot-api-client/src/main/java/com/linecorp/bot/client/LineMessagingClient.java

@@ -30,12 +30,14 @@
 import com.linecorp.bot.model.group.GroupSummaryResponse;
 import com.linecorp.bot.model.profile.MembersIdsResponse;
 import com.linecorp.bot.model.profile.UserProfileResponse;
+import com.linecorp.bot.model.request.GetFollowersRequest;
 import com.linecorp.bot.model.request.SetWebhookEndpointRequest;
 import com.linecorp.bot.model.request.TestWebhookEndpointRequest;
 import com.linecorp.bot.model.response.BotApiResponse;
 import com.linecorp.bot.model.response.BotInfoResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitNameListResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitUsageResponse;
+import com.linecorp.bot.model.response.GetFollowersResponse;
 import com.linecorp.bot.model.response.GetMessageEventResponse;
 import com.linecorp.bot.model.response.GetNumberOfFollowersResponse;
 import com.linecorp.bot.model.response.GetNumberOfMessageDeliveriesResponse;
@@ -402,6 +404,11 @@ CompletableFuture<BotApiResponse> updateRichMenuAlias(String richMenuAliasId,
      */
     CompletableFuture<GetNumberOfFollowersResponse> getNumberOfFollowers(String date);
 
+    /**
+     * Get a list of users who added your LINE Official Account as a friend.
+     */
+    CompletableFuture<GetFollowersResponse> getFollowers(GetFollowersRequest request);
+
     /**
      * Returns statistics about how users interact with narrowcast messages or broadcast messages sent from your
      * LINE Official Account.

line-bot-api-client/src/main/java/com/linecorp/bot/client/LineMessagingClientImpl.java

@@ -31,12 +31,14 @@
 import com.linecorp.bot.model.group.GroupSummaryResponse;
 import com.linecorp.bot.model.profile.MembersIdsResponse;
 import com.linecorp.bot.model.profile.UserProfileResponse;
+import com.linecorp.bot.model.request.GetFollowersRequest;
 import com.linecorp.bot.model.request.SetWebhookEndpointRequest;
 import com.linecorp.bot.model.request.TestWebhookEndpointRequest;
 import com.linecorp.bot.model.response.BotApiResponse;
 import com.linecorp.bot.model.response.BotInfoResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitNameListResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitUsageResponse;
+import com.linecorp.bot.model.response.GetFollowersResponse;
 import com.linecorp.bot.model.response.GetMessageEventResponse;
 import com.linecorp.bot.model.response.GetNumberOfFollowersResponse;
 import com.linecorp.bot.model.response.GetNumberOfMessageDeliveriesResponse;
@@ -314,6 +316,11 @@ public CompletableFuture<GetNumberOfFollowersResponse> getNumberOfFollowers(Stri
         return toFuture(retrofitImpl.getNumberOfFollowers(date));
     }
 
+    @Override
+    public CompletableFuture<GetFollowersResponse> getFollowers(GetFollowersRequest request) {
+        return toFuture(retrofitImpl.getFollowers(request.getNext()));
+    }
+
     @Override
     public CompletableFuture<GetMessageEventResponse> getMessageEvent(String requestId) {
         return toFuture(retrofitImpl.getMessageEvent(requestId));

line-bot-api-client/src/main/java/com/linecorp/bot/client/LineMessagingService.java

@@ -32,6 +32,7 @@
 import com.linecorp.bot.model.response.BotInfoResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitNameListResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitUsageResponse;
+import com.linecorp.bot.model.response.GetFollowersResponse;
 import com.linecorp.bot.model.response.GetMessageEventResponse;
 import com.linecorp.bot.model.response.GetNumberOfFollowersResponse;
 import com.linecorp.bot.model.response.GetNumberOfMessageDeliveriesResponse;
@@ -379,6 +380,12 @@ Call<Void> linkRichMenuToUser(
     @GET("v2/bot/insight/followers")
     Call<GetNumberOfFollowersResponse> getNumberOfFollowers(@Query("date") String date);
 
+    /**
+     * Get a list of users who added your LINE Official Account as a friend.
+     */
+    @GET("v2/bot/followers/ids")
+    Call<GetFollowersResponse> getFollowers(@Query("start") String next);
+
     /**
      * Returns statistics about how users interact with narrowcast messages or broadcast messages sent from your
      * LINE Official Account.

line-bot-api-client/src/test/java/com/linecorp/bot/client/LineMessagingClientImplTest.java

@@ -23,6 +23,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.ArgumentMatchers.nullable;
 import static org.mockito.Mockito.only;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -41,6 +42,8 @@
 import org.mockito.junit.MockitoRule;
 import org.mockito.stubbing.OngoingStubbing;
 
+import com.google.common.collect.ImmutableList;
+
 import com.linecorp.bot.model.Broadcast;
 import com.linecorp.bot.model.Multicast;
 import com.linecorp.bot.model.Narrowcast;
@@ -55,12 +58,14 @@
 import com.linecorp.bot.model.narrowcast.filter.GenderDemographicFilter.Gender;
 import com.linecorp.bot.model.profile.MembersIdsResponse;
 import com.linecorp.bot.model.profile.UserProfileResponse;
+import com.linecorp.bot.model.request.GetFollowersRequest;
 import com.linecorp.bot.model.request.SetWebhookEndpointRequest;
 import com.linecorp.bot.model.request.TestWebhookEndpointRequest;
 import com.linecorp.bot.model.response.BotApiResponse;
 import com.linecorp.bot.model.response.BotInfoResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitNameListResponse;
 import com.linecorp.bot.model.response.GetAggregationUnitUsageResponse;
+import com.linecorp.bot.model.response.GetFollowersResponse;
 import com.linecorp.bot.model.response.GetNumberOfFollowersResponse;
 import com.linecorp.bot.model.response.GetNumberOfMessageDeliveriesResponse;
 import com.linecorp.bot.model.response.GetStatisticsPerUnitResponse;
@@ -864,6 +869,18 @@ public void getAggregationUnitNameListTest() throws Exception {
         assertThat(actual).isEqualTo(response);
     }
 
+    @Test
+    public void getFollowers() throws Exception {
+        final GetFollowersResponse response = GetFollowersResponse
+                .builder()
+                .userIds(ImmutableList.of("U1234"))
+                .build();
+        whenCall(retrofitMock.getFollowers(nullable(String.class)), response);
+        final GetFollowersResponse actual = target.getFollowers(GetFollowersRequest.builder().build()).get();
+        verify(retrofitMock, only()).getFollowers(null);
+        assertThat(actual).isEqualTo(response);
+    }
+
     // Utility methods
 
     private static <T> void whenCall(Call<T> call, T value) {

line-bot-model/src/main/java/com/linecorp/bot/model/request/GetFollowersRequest.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2021 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you 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.linecorp.bot.model.request;
+
+import javax.annotation.Nullable;
+
+import com.linecorp.bot.model.response.GetFollowersResponse;
+
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * A request object to retrieve followers. If you want to retrieve your followers from the beginning, you need
+ * to call getFollowers as follows.
+ * <pre>
+ * {@code
+ * final LineMessagingClient client = ...;
+ * final GetFollowersResponse response = client.getFollowers(GetFollowersRequest.builder().build()).join();
+ * }</pre>
+ * Or if you want to retrieve all followers, you need to call getFollowers API as follows.
+ * <pre>
+ * {@code
+ * final LineMessagingClient client = ...;
+ * GetFollowersRequest request = GetFollowersRequest.builder().build();
+ * while (true) {
+ *   final GetFollowersResponse response = client.getFollowers(request).join();
+ *   final List<String> userIds = response.getUserIds();
+ *   if (response.getNext() == null) { // No remaining user IDs anymore.
+ *     break;
+ *   }
+ *   // You have remaining user IDs. You can retrieve rest of them using following request object.
+ *   request = GetFollowersRequest .fromResponse(response).build();
+ *  }
+ * }</pre>
+ */
+@Value
+@Builder
+public class GetFollowersRequest {
+    /**
+     * Value of the continuation token found in the next property of the JSON object returned in the response.
+     * Include this parameter to get the next array of user IDs.
+     */
+    @Nullable
+    String next;
+
+    public static GetFollowersRequestBuilder fromResponse(GetFollowersResponse response) {
+        return builder().next(response.getNext());
+    }
+
+    public static class GetFollowersRequestBuilder {
+        // Filled by lombok.
+    }
+}

line-bot-model/src/main/java/com/linecorp/bot/model/response/GetFollowersResponse.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2021 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you 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.linecorp.bot.model.response;
+
+import java.util.List;
+
+import javax.annotation.Nullable;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonPOJOBuilder;
+
+import com.linecorp.bot.model.response.GetFollowersResponse.GetFollowersResponseBuilder;
+
+import lombok.Builder;
+import lombok.Value;
+
+@Value
+@Builder
+@JsonDeserialize(builder = GetFollowersResponseBuilder.class)
+public class GetFollowersResponse {
+    /**
+     * List of user IDs of users that have added the LINE Official Account as a friend. Only users of LINE for
+     * iOS and LINE for Android are included in userIds. For more information, see
+     * <a href="https://developers.line.biz/en/docs/messaging-api/user-consent/">Consent on getting user
+     * profile information</a>. Max: 300 user IDs
+     */
+    List<String> userIds;
+
+    /**
+     * A continuation token to get the next array of user IDs. Returned only when there are remaining user IDs
+     * that were not returned in userIds in the original request. The number of user IDs in the userIds element
+     * does not have to reach 300 for the next property to be included in the response.
+     */
+    @Nullable
+    String next;
+
+    @JsonPOJOBuilder(withPrefix = "")
+    public static class GetFollowersResponseBuilder {
+        // Filled by lombok
+    }
+}