feat(stopwords): add stopwords support (#73)

Implements stopwords management capabilities allowing users to create and manage
stopwords sets for search optimization. Adds complete CRUD operations for
stopwords with proper error handling and test coverage.

Changes include:
- New Stopwords and StopwordsSet classes for managing stopwords
- Client integration for stopwords management
- Full test coverage with realistic scenarios
- Helper class updates for testing stopwords functionality
- Documentation updates with usage examples

feat(stopwords): add Stopwords class for bulk operations
feat(stopwords): add StopwordsSet class for individual set management
test(stopwords): add StopwordsTest test coverage
refactor(client): integrate stopwords support
refactor(helper): add stopwords support in test helper
docs(stopwords): add documentation and examples

Author: tharropoulos

README.md

@@ -206,6 +206,34 @@ AnalyticsEventCreateSchema analyticsEvent = new AnalyticsEventCreateSchema()
 client.analytics().events().create(analyticsEvent);
 ```
 
+### Upsert a stopwords set
+```java
+List<String> stopwords = new ArrayList<>();
+stopwords.add("the");
+stopwords.add("of");
+stopwords.add("and");
+
+StopwordsSetUpsertSchema stopwordsSet = new StopwordsSetUpsertSchema();
+stopwordsSet.stopwords(stopwords);
+
+client.stopwords().upsert("common-words", stopwordsSet);
+```
+
+### Retrieve a stopwords set
+```java
+StopwordsSetRetrieveSchema set = client.stopwords("common-words").retrieve();
+```
+
+### Retrieve all stopwords sets
+```java
+StopwordsSetsRetrieveAllSchema sets = client.stopwords().retrieve();
+```
+
+### Delete a stopwords set
+```java
+client.stopwords("common-words").delete();
+```
+
 ### Create an API key
 ```java
 ApiKeySchema apiKeySchema = new ApiKeySchema();

src/main/java/org/typesense/api/Client.java

@@ -21,6 +21,9 @@ public class Client {
 
     private Analytics analytics;
 
+    private Stopwords stopwords;
+    private Map<String, StopwordsSet> individualStopwordsSets;
+
     public Health health;
     public Operations operations;
     public Metrics metrics;
@@ -42,6 +45,8 @@ public Client(Configuration configuration){
         this.debug = new Debug(this.apiCall);
         this.multiSearch = new MultiSearch(this.apiCall);
         this.analytics = new Analytics(this.apiCall);
+        this.stopwords = new Stopwords(this.apiCall);
+        this.individualStopwordsSets = new HashMap<>();
     }
 
     public Collection collections(String name){
@@ -94,4 +99,19 @@ public Key keys(Long id){
     public Analytics analytics(){
         return this.analytics;
     }
+
+    public Stopwords stopwords() {
+        return this.stopwords;
+    }
+
+    public StopwordsSet stopwords(String stopwordsSetId) {
+        StopwordsSet retVal;
+
+        if (!this.individualStopwordsSets.containsKey(stopwordsSetId)) {
+            this.individualStopwordsSets.put(stopwordsSetId, new StopwordsSet(stopwordsSetId, this.apiCall));
+        }
+
+        retVal = this.individualStopwordsSets.get(stopwordsSetId);
+        return retVal;
+    }
 }

src/main/java/org/typesense/api/Stopwords.java

@@ -0,0 +1,29 @@
+package org.typesense.api;
+
+import org.typesense.api.utils.URLEncoding;
+import org.typesense.model.StopwordsSetSchema;
+import org.typesense.model.StopwordsSetUpsertSchema;
+import org.typesense.model.StopwordsSetsRetrieveAllSchema;
+
+public class Stopwords {
+    public final static String RESOURCEPATH = "/stopwords";
+
+    private final ApiCall apiCall;
+
+    public Stopwords(ApiCall apiCall) {
+        this.apiCall = apiCall;
+    }
+
+    public StopwordsSetSchema upsert(String stopwordSetId, StopwordsSetUpsertSchema stopwordSet) throws Exception {
+        return this.apiCall.put(getEndpoint(stopwordSetId), stopwordSet, null, StopwordsSetSchema.class);
+    }
+
+    public StopwordsSetsRetrieveAllSchema retrieve() throws Exception {
+        return this.apiCall.get(Stopwords.RESOURCEPATH, null, StopwordsSetsRetrieveAllSchema.class);
+    }
+
+    private String getEndpoint(String stopwordSetId) {
+        return RESOURCEPATH + "/" + URLEncoding.encodeURIComponent(stopwordSetId);
+    }
+
+}

src/main/java/org/typesense/api/StopwordsSet.java

@@ -0,0 +1,28 @@
+package org.typesense.api;
+
+import org.typesense.api.utils.URLEncoding;
+import org.typesense.model.StopwordsSetRetrieveSchema;
+import org.typesense.model.StopwordsSetSchema;
+
+public class StopwordsSet {
+    private final ApiCall apiCall;
+    private final String stopwordsSetId;
+
+    public StopwordsSet(String stopwordsSetId, ApiCall apiCall) {
+        this.stopwordsSetId = stopwordsSetId;
+        this.apiCall = apiCall;
+    }
+
+    public StopwordsSetRetrieveSchema retrieve() throws Exception {
+        return this.apiCall.get(this.getEndpoint(), null, StopwordsSetRetrieveSchema.class);
+    }
+
+    public StopwordsSetSchema delete() throws Exception {
+        return this.apiCall.delete(this.getEndpoint(), null, StopwordsSetSchema.class);
+    }
+
+    private String getEndpoint() {
+        return Stopwords.RESOURCEPATH + "/" + URLEncoding.encodeURIComponent(this.stopwordsSetId);
+    }
+
+}

src/test/java/org/typesense/api/Helper.java

@@ -25,6 +25,9 @@
 import org.typesense.model.SearchOverrideRule;
 import org.typesense.model.SearchOverrideSchema;
 import org.typesense.model.SearchSynonymSchema;
+import org.typesense.model.StopwordsSetSchema;
+import org.typesense.model.StopwordsSetUpsertSchema;
+import org.typesense.model.StopwordsSetsRetrieveAllSchema;
 import org.typesense.resources.Node;
 
 public class Helper {
@@ -125,6 +128,18 @@ public void createTestAnalyticsRule() throws Exception {
         client.analytics().rules().upsert("analytics-rule", analyticsRuleSchema);
     }
 
+    public void createTestStopwordsSet() throws Exception {
+        List<String> stopwords = new ArrayList<>();
+        stopwords.add("the");
+        stopwords.add("of");
+        stopwords.add("and");
+
+        StopwordsSetUpsertSchema stopwordsSetSchema = new StopwordsSetUpsertSchema();
+        stopwordsSetSchema.stopwords(stopwords);
+
+        client.stopwords().upsert("common-words", stopwordsSetSchema);
+    }
+
     public void teardown() throws Exception {
         CollectionResponse[] collectionResponses = client.collections().retrieve();
         for (CollectionResponse c : collectionResponses) {
@@ -145,5 +160,10 @@ public void teardown() throws Exception {
         for (ApiKey k : apiKeysResponse.getKeys()) {
             client.keys(k.getId()).delete();
         }
+
+        StopwordsSetsRetrieveAllSchema stopwords = client.stopwords().retrieve();
+        for (StopwordsSetSchema s : stopwords.getStopwords()) {
+            client.stopwords(s.getId()).delete();
+        }
     }
 }

src/test/java/org/typesense/api/StopwordsTest.java

@@ -0,0 +1,91 @@
+package org.typesense.api;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.junit.jupiter.api.AfterEach;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.typesense.model.StopwordsSetRetrieveSchema;
+import org.typesense.model.StopwordsSetSchema;
+import org.typesense.model.StopwordsSetUpsertSchema;
+import org.typesense.model.StopwordsSetsRetrieveAllSchema;
+
+public class StopwordsTest {
+
+    private Client client;
+    private Helper helper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        helper = new Helper();
+        client = helper.getClient();
+        helper.teardown();
+        helper.createTestCollection();
+    }
+
+    @AfterEach
+    void tearDown() throws Exception {
+        helper.teardown();
+    }
+
+    @Test
+    void testUpsert() throws Exception {
+        List<String> stopwords = new ArrayList<>();
+        stopwords.add("the");
+        stopwords.add("of");
+        stopwords.add("and");
+
+        StopwordsSetUpsertSchema stopwordsSetSchema = new StopwordsSetUpsertSchema();
+        stopwordsSetSchema.stopwords(stopwords);
+
+        client.stopwords().upsert("common-words", stopwordsSetSchema);
+    }
+
+    @Test
+    void testRetrieve() throws Exception {
+        helper.createTestStopwordsSet();
+
+        StopwordsSetRetrieveSchema result = this.client.stopwords("common-words").retrieve();
+
+        assertNotNull(result);
+
+        StopwordsSetSchema set = result.getStopwords();
+
+        assertEquals("common-words", set.getId());
+        assertEquals(3, set.getStopwords().size());
+        assertEquals("and", set.getStopwords().get(0));
+        assertEquals("the", set.getStopwords().get(1));
+        assertEquals("of", set.getStopwords().get(2));
+    }
+
+    @Test
+    void testRetrieveAll() throws Exception {
+        helper.createTestStopwordsSet();
+
+        StopwordsSetsRetrieveAllSchema result = this.client.stopwords().retrieve();
+
+        assertNotNull(result);
+        assertEquals(1, result.getStopwords().size());
+
+        StopwordsSetSchema set = result.getStopwords().get(0);
+
+        assertEquals("common-words", set.getId());
+        assertEquals(3, set.getStopwords().size());
+        assertEquals("and", set.getStopwords().get(0));
+        assertEquals("the", set.getStopwords().get(1));
+        assertEquals("of", set.getStopwords().get(2));
+    }
+
+    @Test
+    void testDelete() throws Exception {
+        helper.createTestStopwordsSet();
+
+        StopwordsSetSchema result = this.client.stopwords("common-words").delete();
+
+        assertNotNull(result);
+        assertEquals("common-words", result.getId());
+    }
+}