MT-22678: Add search query param to contact lists findAll

README.md

@@ -369,7 +369,7 @@ You can find the [Mailtrap Java API reference](https://mailtrap.github.io/mailtr
 ### Contacts API
 
 - [Contacts](examples/java/io/mailtrap/examples/contacts/ContactsExample.java)
-- [Contact Lists](examples/java/io/mailtrap/examples/contactlists/ContactListsExample.java)
+- [Contact Lists](examples/java/io/mailtrap/examples/contactlists/ContactListsExample.java) (incl. filtering lists by name via the `search` query param — case-insensitive prefix match)
 - [Contact Exports](examples/java/io/mailtrap/examples/contactexports/ContactExportsExample.java)
 - [Contact Fields](examples/java/io/mailtrap/examples/contactfields/ContactFieldsExample.java)
 - [Contact Imports](examples/java/io/mailtrap/examples/contactimports/ContactImportsExample.java)

examples/java/io/mailtrap/examples/contactlists/ContactListsExample.java

@@ -3,13 +3,15 @@
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.factory.MailtrapClientFactory;
 import io.mailtrap.model.request.contactlists.ContactListRequest;
+import io.mailtrap.model.request.contactlists.ListContactListsQueryParams;
 
 public class ContactListsExample {
 
     private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
     private static final long ACCOUNT_ID = 1L;
     private static final String NAME_FOR_CREATE = "Clients";
     private static final String NAME_FOR_UPDATE = "Customers";
+    private static final String SEARCH_QUERY = "Cust";
 
     public static void main(String[] args) {
         final var config = new MailtrapConfig.Builder()
@@ -30,6 +32,11 @@ public static void main(String[] args) {
         final var contactLists = client.contactsApi().contactLists().findAll(ACCOUNT_ID);
         System.out.println(contactLists);
 
+        // Filter contact lists by name (case-insensitive prefix match)
+        final var searchParams = new ListContactListsQueryParams(SEARCH_QUERY);
+        final var matchingContactLists = client.contactsApi().contactLists().findAll(ACCOUNT_ID, searchParams);
+        System.out.println(matchingContactLists);
+
         client.contactsApi().contactLists().deleteContactList(ACCOUNT_ID, byId.getId());
     }
 }

src/main/java/io/mailtrap/api/contactlists/ContactLists.java

@@ -1,6 +1,7 @@
 package io.mailtrap.api.contactlists;
 
 import io.mailtrap.model.request.contactlists.ContactListRequest;
+import io.mailtrap.model.request.contactlists.ListContactListsQueryParams;
 import io.mailtrap.model.response.contactlists.ContactListResponse;
 
 import java.util.List;
@@ -15,6 +16,16 @@ public interface ContactLists {
      */
     List<ContactListResponse> findAll(long accountId);
 
+    /**
+     * Get all contact lists existing in account, optionally filtered by name.
+     *
+     * @param accountId   unique account ID
+     * @param queryParams additional query parameters. The {@code search} value filters
+     *                    contact lists by name using a case-insensitive prefix match
+     * @return contacts list
+     */
+    List<ContactListResponse> findAll(long accountId, ListContactListsQueryParams queryParams);
+
     /**
      * Create new Contact List
      *

src/main/java/io/mailtrap/api/contactlists/ContactListsImpl.java

@@ -5,9 +5,14 @@
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.http.RequestData;
 import io.mailtrap.model.request.contactlists.ContactListRequest;
+import io.mailtrap.model.request.contactlists.ListContactListsQueryParams;
 import io.mailtrap.model.response.contactlists.ContactListResponse;
+import lombok.NonNull;
 
 import java.util.List;
+import java.util.Optional;
+
+import static io.mailtrap.http.RequestData.entry;
 
 public class ContactListsImpl extends ApiResource implements ContactLists {
 
@@ -18,9 +23,17 @@ public ContactListsImpl(final MailtrapConfig config) {
 
     @Override
     public List<ContactListResponse> findAll(final long accountId) {
+        return findAll(accountId, ListContactListsQueryParams.empty());
+    }
+
+    @Override
+    public List<ContactListResponse> findAll(final long accountId, @NonNull final ListContactListsQueryParams queryParams) {
+        final var params = RequestData.buildQueryParams(
+            entry("search", Optional.ofNullable(queryParams.getSearch())));
+
         return httpClient.getList(
             String.format(apiHost + "/api/accounts/%d/contacts/lists", accountId),
-            new RequestData(),
+            new RequestData(params),
             ContactListResponse.class
         );
     }

src/main/java/io/mailtrap/model/request/contactlists/ListContactListsQueryParams.java

@@ -0,0 +1,27 @@
+package io.mailtrap.model.request.contactlists;
+
+import io.mailtrap.api.contactlists.ContactLists;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class ListContactListsQueryParams {
+
+    /**
+     * Filter contact lists by name (case-insensitive prefix match)
+     */
+    private String search;
+
+    /**
+     * Creates an instance of {@link ListContactListsQueryParams} with no query parameters set.
+     * This is useful when you want to call the {@link ContactLists#findAll} method without any optional parameters.
+     *
+     * @return A new instance with no parameters set
+     */
+    public static ListContactListsQueryParams empty() {
+        return new ListContactListsQueryParams();
+    }
+}

src/test/java/io/mailtrap/api/contactlists/ContactListsImplTest.java

@@ -4,6 +4,7 @@
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.factory.MailtrapClientFactory;
 import io.mailtrap.model.request.contactlists.ContactListRequest;
+import io.mailtrap.model.request.contactlists.ListContactListsQueryParams;
 import io.mailtrap.model.response.contactlists.ContactListResponse;
 import io.mailtrap.testutils.BaseTest;
 import io.mailtrap.testutils.DataMock;
@@ -12,6 +13,7 @@
 import org.junit.jupiter.api.Test;
 
 import java.util.List;
+import java.util.Map;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -23,6 +25,10 @@ public void init() {
         final TestHttpClient httpClient = new TestHttpClient(List.of(
             DataMock.build(Constants.GENERAL_HOST + "/api/accounts/" + accountId + "/contacts/lists",
                 "GET", null, "api/contact_lists/contactLists.json"),
+            DataMock.build(Constants.GENERAL_HOST + "/api/accounts/" + accountId + "/contacts/lists",
+                "GET", null, "api/contact_lists/contactListsWithSearchEmptyResponse.json", Map.of("search", "qqqqqqqq")),
+            DataMock.build(Constants.GENERAL_HOST + "/api/accounts/" + accountId + "/contacts/lists",
+                "GET", null, "api/contact_lists/contactListsWithSearchSingleResponse.json", Map.of("search", "Cust")),
             DataMock.build(Constants.GENERAL_HOST + "/api/accounts/" + accountId + "/contacts/lists",
                 "POST", "api/contact_lists/createRequest.json", "api/contact_lists/contactList.json"),
             DataMock.build(Constants.GENERAL_HOST + "/api/accounts/" + accountId + "/contacts/lists/" + contactListId,
@@ -49,6 +55,29 @@ void test_findAll() {
         assertEquals(2, contacts.size());
     }
 
+    @Test
+    void test_findAllWithSearchQueryParam_emptyResponse() {
+        final ListContactListsQueryParams queryParams = new ListContactListsQueryParams();
+        queryParams.setSearch("qqqqqqqq");
+
+        final List<ContactListResponse> contacts = api.findAll(accountId, queryParams);
+
+        assertNotNull(contacts);
+        assertTrue(contacts.isEmpty());
+    }
+
+    @Test
+    void test_findAllWithSearchQueryParam_notEmptyResponse() {
+        final ListContactListsQueryParams queryParams = new ListContactListsQueryParams();
+        queryParams.setSearch("Cust");
+
+        final List<ContactListResponse> contacts = api.findAll(accountId, queryParams);
+
+        assertNotNull(contacts);
+        assertEquals(1, contacts.size());
+        assertEquals(contactListId, contacts.get(0).getId());
+    }
+
     @Test
     void test_create() {
         final ContactListResponse contactList = api.createContactList(accountId, new ContactListRequest("Customers"));

src/test/resources/api/contact_lists/contactListsWithSearchEmptyResponse.json

@@ -0,0 +1 @@
+[]

src/test/resources/api/contact_lists/contactListsWithSearchSingleResponse.json

@@ -0,0 +1,6 @@
+[
+  {
+    "id": 1337,
+    "name": "Customers"
+  }
+]