feat(api): API Endpoints for lists of unread entry IDs and starred entry IDs

client/client.go

@@ -888,6 +888,55 @@ func (c *Client) EntryContext(ctx context.Context, entryID int64) (*Entry, error
 	return entry, nil
 }
 
+// EntryIDs returns entry IDs for the current user, optionally filtered by starred status and/or read status.
+func (c *Client) EntryIDs(filter *EntryIDsFilter) (*EntryIDsResultSet, error) {
+	ctx, cancel := withDefaultTimeout()
+	defer cancel()
+	return c.EntryIDsContext(ctx, filter)
+}
+
+// EntryIDsContext returns entry IDs for the current user, optionally filtered by starred status and/or read status.
+func (c *Client) EntryIDsContext(ctx context.Context, filter *EntryIDsFilter) (*EntryIDsResultSet, error) {
+	body, err := c.request.Get(ctx, buildEntryIDsFilterQueryString("/v1/entries/ids", filter))
+	if err != nil {
+		return nil, err
+	}
+	defer body.Close()
+
+	var result EntryIDsResultSet
+	if err := json.NewDecoder(body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("miniflux: response error (%v)", err)
+	}
+
+	return &result, nil
+}
+
+func buildEntryIDsFilterQueryString(path string, filter *EntryIDsFilter) string {
+	if filter == nil {
+		return path
+	}
+
+	params := url.Values{}
+	if filter.Limit > 0 {
+		params.Set("limit", strconv.Itoa(filter.Limit))
+	}
+	if filter.Offset > 0 {
+		params.Set("offset", strconv.Itoa(filter.Offset))
+	}
+	if filter.Starred != nil {
+		params.Set("starred", strconv.FormatBool(*filter.Starred))
+	}
+	if filter.Status != "" {
+		params.Set("status", filter.Status)
+	}
+
+	if len(params) == 0 {
+		return path
+	}
+
+	return path + "?" + params.Encode()
+}
+
 // Entries fetches entries using the given filter.
 func (c *Client) Entries(filter *Filter) (*EntryResultSet, error) {
 	ctx, cancel := withDefaultTimeout()

client/client_test.go

@@ -1286,3 +1286,110 @@ func TestUpdateEnclosure(t *testing.T) {
 		t.Fatalf("Expected no error, got %v", err)
 	}
 }
+
+func boolPtr(b bool) *bool { return &b }
+
+func TestEntryIDsNoFilter(t *testing.T) {
+	expected := &EntryIDsResultSet{
+		Total:    2,
+		EntryIDs: []int64{1, 2},
+	}
+	client := NewClientWithOptions(
+		"http://mf",
+		WithHTTPClient(
+			newFakeHTTPClient(t, func(t *testing.T, req *http.Request) *http.Response {
+				expectRequest(t, http.MethodGet, "http://mf/v1/entries/ids", nil, req)
+				return jsonResponseFrom(t, http.StatusOK, http.Header{}, expected)
+			})))
+	res, err := client.EntryIDsContext(t.Context(), nil)
+	if err != nil {
+		t.Fatalf("Expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res, expected) {
+		t.Fatalf("Expected %s, got %s", asJSON(expected), asJSON(res))
+	}
+}
+
+func TestEntryIDsWithPaginationFilter(t *testing.T) {
+	expected := &EntryIDsResultSet{
+		Total:    5,
+		EntryIDs: []int64{3},
+	}
+	client := NewClientWithOptions(
+		"http://mf",
+		WithHTTPClient(
+			newFakeHTTPClient(t, func(t *testing.T, req *http.Request) *http.Response {
+				expectRequest(t, http.MethodGet, "http://mf/v1/entries/ids?limit=1&offset=2", nil, req)
+				return jsonResponseFrom(t, http.StatusOK, http.Header{}, expected)
+			})))
+	res, err := client.EntryIDsContext(t.Context(), &EntryIDsFilter{Limit: 1, Offset: 2})
+	if err != nil {
+		t.Fatalf("Expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res, expected) {
+		t.Fatalf("Expected %s, got %s", asJSON(expected), asJSON(res))
+	}
+}
+
+func TestEntryIDsWithStarredFilter(t *testing.T) {
+	expected := &EntryIDsResultSet{
+		Total:    1,
+		EntryIDs: []int64{42},
+	}
+	client := NewClientWithOptions(
+		"http://mf",
+		WithHTTPClient(
+			newFakeHTTPClient(t, func(t *testing.T, req *http.Request) *http.Response {
+				expectRequest(t, http.MethodGet, "http://mf/v1/entries/ids?starred=true", nil, req)
+				return jsonResponseFrom(t, http.StatusOK, http.Header{}, expected)
+			})))
+	res, err := client.EntryIDsContext(t.Context(), &EntryIDsFilter{Starred: boolPtr(true)})
+	if err != nil {
+		t.Fatalf("Expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res, expected) {
+		t.Fatalf("Expected %s, got %s", asJSON(expected), asJSON(res))
+	}
+}
+
+func TestEntryIDsWithStatusFilter(t *testing.T) {
+	expected := &EntryIDsResultSet{
+		Total:    10,
+		EntryIDs: []int64{7, 8},
+	}
+	client := NewClientWithOptions(
+		"http://mf",
+		WithHTTPClient(
+			newFakeHTTPClient(t, func(t *testing.T, req *http.Request) *http.Response {
+				expectRequest(t, http.MethodGet, "http://mf/v1/entries/ids?status=unread", nil, req)
+				return jsonResponseFrom(t, http.StatusOK, http.Header{}, expected)
+			})))
+	res, err := client.EntryIDsContext(t.Context(), &EntryIDsFilter{Status: EntryStatusUnread})
+	if err != nil {
+		t.Fatalf("Expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res, expected) {
+		t.Fatalf("Expected %s, got %s", asJSON(expected), asJSON(res))
+	}
+}
+
+func TestEntryIDsWithCombinedFilter(t *testing.T) {
+	expected := &EntryIDsResultSet{
+		Total:    3,
+		EntryIDs: []int64{5},
+	}
+	client := NewClientWithOptions(
+		"http://mf",
+		WithHTTPClient(
+			newFakeHTTPClient(t, func(t *testing.T, req *http.Request) *http.Response {
+				expectRequest(t, http.MethodGet, "http://mf/v1/entries/ids?limit=2&offset=5&starred=false&status=read", nil, req)
+				return jsonResponseFrom(t, http.StatusOK, http.Header{}, expected)
+			})))
+	res, err := client.EntryIDsContext(t.Context(), &EntryIDsFilter{Limit: 2, Offset: 5, Starred: boolPtr(false), Status: EntryStatusRead})
+	if err != nil {
+		t.Fatalf("Expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res, expected) {
+		t.Fatalf("Expected %s, got %s", asJSON(expected), asJSON(res))
+	}
+}

client/model.go

@@ -327,6 +327,20 @@ type EntryResultSet struct {
 	Entries Entries `json:"entries"`
 }
 
+// EntryIDsFilter holds optional filter and pagination parameters for the entry IDs endpoint.
+type EntryIDsFilter struct {
+	Limit   int
+	Offset  int
+	Starred *bool
+	Status  string
+}
+
+// EntryIDsResultSet represents the response when fetching entry ID lists.
+type EntryIDsResultSet struct {
+	Total    int     `json:"total"`
+	EntryIDs []int64 `json:"entry_ids"`
+}
+
 // VersionResponse represents the version and the build information of the Miniflux instance.
 type VersionResponse struct {
 	Version   string `json:"version"`

internal/api/api.go

@@ -54,6 +54,7 @@ func NewHandler(store *storage.Storage, pool *worker.Pool) http.Handler {
 	mux.HandleFunc("GET /v1/feeds/{feedID}/entries", handler.getFeedEntriesHandler)
 	mux.HandleFunc("POST /v1/feeds/{feedID}/entries/import", handler.importFeedEntryHandler)
 	mux.HandleFunc("GET /v1/feeds/{feedID}/entries/{entryID}", handler.getFeedEntryHandler)
+	mux.HandleFunc("GET /v1/entries/ids", handler.getEntryIDsHandler)
 	mux.HandleFunc("GET /v1/entries", handler.getEntriesHandler)
 	mux.HandleFunc("PUT /v1/entries", handler.setEntryStatusHandler)
 	mux.HandleFunc("GET /v1/entries/{entryID}", handler.getEntryHandler)