miniflux_v2/client/client.go

// SPDX-FileCopyrightText: Copyright The Miniflux Authors. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

package client // import "miniflux.app/v2/client"

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
	"strings"
)

// Client holds API procedure calls.
type Client struct {
	request *request
}

// New returns a new Miniflux client.
//
// Deprecated: use NewClient instead.
//
//go:fix inline
func New(endpoint string, credentials ...string) *Client {
	return NewClient(endpoint, credentials...)
}

// NewClient returns a new Miniflux client.
func NewClient(endpoint string, credentials ...string) *Client {
	switch len(credentials) {
	case 2:
		return NewClientWithOptions(endpoint, WithCredentials(credentials[0], credentials[1]))
	case 1:
		return NewClientWithOptions(endpoint, WithAPIKey(credentials[0]))
	default:
		return NewClientWithOptions(endpoint)
	}
}

// NewClientWithOptions returns a new Miniflux client with options.
func NewClientWithOptions(endpoint string, options ...Option) *Client {
	// Trim trailing slashes and /v1 from the endpoint.
	endpoint = strings.TrimSuffix(endpoint, "/")
	endpoint = strings.TrimSuffix(endpoint, "/v1")
	request := &request{endpoint: endpoint, client: http.DefaultClient}

	for _, option := range options {
		option(request)
	}

	return &Client{request: request}
}

func withDefaultTimeout() (context.Context, func()) {
	ctx, cancel := context.WithTimeout(context.Background(), defaultTimeout)
	return ctx, cancel
}

// Healthcheck checks if the application is up and running.
func (c *Client) Healthcheck() error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.HealthcheckContext(ctx)
}

// HealthcheckContext checks if the application is up and running.
func (c *Client) HealthcheckContext(ctx context.Context) error {
	body, err := c.request.Get(ctx, "/healthcheck")
	if err != nil {
		return fmt.Errorf("miniflux: unable to perform healthcheck: %w", err)
	}
	defer body.Close()

	responseBodyContent, err := io.ReadAll(body)
	if err != nil {
		return fmt.Errorf("miniflux: unable to read healthcheck response: %w", err)
	}

	if string(responseBodyContent) != "OK" {
		return fmt.Errorf("miniflux: invalid healthcheck response: %q", responseBodyContent)
	}

	return nil
}

// Version returns the version of the Miniflux instance.
func (c *Client) Version() (*VersionResponse, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.VersionContext(ctx)
}

// VersionContext returns the version of the Miniflux instance.
func (c *Client) VersionContext(ctx context.Context) (*VersionResponse, error) {
	body, err := c.request.Get(ctx, "/v1/version")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var versionResponse *VersionResponse
	if err := json.NewDecoder(body).Decode(&versionResponse); err != nil {
		return nil, fmt.Errorf("miniflux: json error (%v)", err)
	}

	return versionResponse, nil
}

// Me returns the logged user information.
func (c *Client) Me() (*User, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.MeContext(ctx)
}

// MeContext returns the logged user information.
func (c *Client) MeContext(ctx context.Context) (*User, error) {
	body, err := c.request.Get(ctx, "/v1/me")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var user *User
	if err := json.NewDecoder(body).Decode(&user); err != nil {
		return nil, fmt.Errorf("miniflux: json error (%v)", err)
	}

	return user, nil
}

// Users returns all users.
func (c *Client) Users() (Users, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UsersContext(ctx)
}

// UsersContext returns all users.
func (c *Client) UsersContext(ctx context.Context) (Users, error) {
	body, err := c.request.Get(ctx, "/v1/users")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var users Users
	if err := json.NewDecoder(body).Decode(&users); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return users, nil
}

// UserByID returns a single user.
func (c *Client) UserByID(userID int64) (*User, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UserByIDContext(ctx, userID)
}

// UserByIDContext returns a single user.
func (c *Client) UserByIDContext(ctx context.Context, userID int64) (*User, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/users/%d", userID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var user User
	if err := json.NewDecoder(body).Decode(&user); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &user, nil
}

// UserByUsername returns a single user.
func (c *Client) UserByUsername(username string) (*User, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UserByUsernameContext(ctx, username)
}

// UserByUsernameContext returns a single user.
func (c *Client) UserByUsernameContext(ctx context.Context, username string) (*User, error) {
	body, err := c.request.Get(ctx, "/v1/users/"+username)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var user User
	if err := json.NewDecoder(body).Decode(&user); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &user, nil
}

// CreateUser creates a new user in the system.
func (c *Client) CreateUser(username, password string, isAdmin bool) (*User, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CreateUserContext(ctx, username, password, isAdmin)
}

// CreateUserContext creates a new user in the system.
func (c *Client) CreateUserContext(ctx context.Context, username, password string, isAdmin bool) (*User, error) {
	body, err := c.request.Post(ctx, "/v1/users", &UserCreationRequest{
		Username: username,
		Password: password,
		IsAdmin:  isAdmin,
	})
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var user *User
	if err := json.NewDecoder(body).Decode(&user); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return user, nil
}

// UpdateUser updates a user in the system.
func (c *Client) UpdateUser(userID int64, userChanges *UserModificationRequest) (*User, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateUserContext(ctx, userID, userChanges)
}

// UpdateUserContext updates a user in the system.
func (c *Client) UpdateUserContext(ctx context.Context, userID int64, userChanges *UserModificationRequest) (*User, error) {
	body, err := c.request.Put(ctx, fmt.Sprintf("/v1/users/%d", userID), userChanges)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var u *User
	if err := json.NewDecoder(body).Decode(&u); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return u, nil
}

// DeleteUser removes a user from the system.
func (c *Client) DeleteUser(userID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.DeleteUserContext(ctx, userID)
}

// DeleteUserContext removes a user from the system.
func (c *Client) DeleteUserContext(ctx context.Context, userID int64) error {
	return c.request.Delete(ctx, fmt.Sprintf("/v1/users/%d", userID))
}

// APIKeys returns all API keys for the authenticated user.
func (c *Client) APIKeys() (APIKeys, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.APIKeysContext(ctx)
}

// APIKeysContext returns all API keys for the authenticated user.
func (c *Client) APIKeysContext(ctx context.Context) (APIKeys, error) {
	body, err := c.request.Get(ctx, "/v1/api-keys")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var apiKeys APIKeys
	if err := json.NewDecoder(body).Decode(&apiKeys); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return apiKeys, nil
}

// CreateAPIKey creates a new API key for the authenticated user.
func (c *Client) CreateAPIKey(description string) (*APIKey, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CreateAPIKeyContext(ctx, description)
}

// CreateAPIKeyContext creates a new API key for the authenticated user.
func (c *Client) CreateAPIKeyContext(ctx context.Context, description string) (*APIKey, error) {
	body, err := c.request.Post(ctx, "/v1/api-keys", &APIKeyCreationRequest{
		Description: description,
	})
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var apiKey *APIKey
	if err := json.NewDecoder(body).Decode(&apiKey); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return apiKey, nil
}

// DeleteAPIKey removes an API key for the authenticated user.
func (c *Client) DeleteAPIKey(apiKeyID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.DeleteAPIKeyContext(ctx, apiKeyID)
}

// DeleteAPIKeyContext removes an API key for the authenticated user.
func (c *Client) DeleteAPIKeyContext(ctx context.Context, apiKeyID int64) error {
	return c.request.Delete(ctx, fmt.Sprintf("/v1/api-keys/%d", apiKeyID))
}

// MarkAllAsRead marks all unread entries as read for a given user.
func (c *Client) MarkAllAsRead(userID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.MarkAllAsReadContext(ctx, userID)
}

// MarkAllAsReadContext marks all unread entries as read for a given user.
func (c *Client) MarkAllAsReadContext(ctx context.Context, userID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/users/%d/mark-all-as-read", userID), nil)
	return err
}

// IntegrationsStatus fetches the integrations status for the signed-in user.
func (c *Client) IntegrationsStatus() (bool, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.IntegrationsStatusContext(ctx)
}

// IntegrationsStatusContext fetches the integrations status for the signed-in user.
func (c *Client) IntegrationsStatusContext(ctx context.Context) (bool, error) {
	body, err := c.request.Get(ctx, "/v1/integrations/status")
	if err != nil {
		return false, err
	}
	defer body.Close()

	var response struct {
		HasIntegrations bool `json:"has_integrations"`
	}

	if err := json.NewDecoder(body).Decode(&response); err != nil {
		return false, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return response.HasIntegrations, nil
}

// Discover tries to find subscriptions on a website.
func (c *Client) Discover(url string) (Subscriptions, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.DiscoverContext(ctx, url)
}

// DiscoverContext tries to find subscriptions from a website.
func (c *Client) DiscoverContext(ctx context.Context, url string) (Subscriptions, error) {
	body, err := c.request.Post(ctx, "/v1/discover", map[string]string{"url": url})
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var subscriptions Subscriptions
	if err := json.NewDecoder(body).Decode(&subscriptions); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return subscriptions, nil
}

// Categories retrieves the list of categories.
func (c *Client) Categories() (Categories, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CategoriesContext(ctx)
}

// CategoriesContext retrieves the list of categories.
func (c *Client) CategoriesContext(ctx context.Context) (Categories, error) {
	body, err := c.request.Get(ctx, "/v1/categories")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var categories Categories
	if err := json.NewDecoder(body).Decode(&categories); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return categories, nil
}

// CategoriesWithCounters fetches the categories with their respective feed and unread counts.
func (c *Client) CategoriesWithCounters() (Categories, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CategoriesWithCountersContext(ctx)
}

// CategoriesWithCountersContext fetches the categories with their respective feed and unread counts.
func (c *Client) CategoriesWithCountersContext(ctx context.Context) (Categories, error) {
	body, err := c.request.Get(ctx, "/v1/categories?counts=true")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var categories Categories
	if err := json.NewDecoder(body).Decode(&categories); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return categories, nil
}

// CreateCategory creates a new category.
func (c *Client) CreateCategory(title string) (*Category, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CreateCategoryContext(ctx, title)
}

// CreateCategoryContext creates a new category.
func (c *Client) CreateCategoryContext(ctx context.Context, title string) (*Category, error) {
	body, err := c.request.Post(ctx, "/v1/categories", &CategoryCreationRequest{
		Title: title,
	})
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var category *Category
	if err := json.NewDecoder(body).Decode(&category); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return category, nil
}

// CreateCategoryWithOptions creates a new category with options.
func (c *Client) CreateCategoryWithOptions(createRequest *CategoryCreationRequest) (*Category, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CreateCategoryWithOptionsContext(ctx, createRequest)
}

// CreateCategoryWithOptionsContext creates a new category with options.
func (c *Client) CreateCategoryWithOptionsContext(ctx context.Context, createRequest *CategoryCreationRequest) (*Category, error) {
	body, err := c.request.Post(ctx, "/v1/categories", createRequest)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var category *Category
	if err := json.NewDecoder(body).Decode(&category); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}
	return category, nil
}

// UpdateCategory updates a category.
func (c *Client) UpdateCategory(categoryID int64, title string) (*Category, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateCategoryContext(ctx, categoryID, title)
}

// UpdateCategoryContext updates a category.
func (c *Client) UpdateCategoryContext(ctx context.Context, categoryID int64, title string) (*Category, error) {
	body, err := c.request.Put(ctx, fmt.Sprintf("/v1/categories/%d", categoryID), &CategoryModificationRequest{
		Title: new(title),
	})
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var category *Category
	if err := json.NewDecoder(body).Decode(&category); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return category, nil
}

// UpdateCategoryWithOptions updates a category with options.
func (c *Client) UpdateCategoryWithOptions(categoryID int64, categoryChanges *CategoryModificationRequest) (*Category, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateCategoryWithOptionsContext(ctx, categoryID, categoryChanges)
}

// UpdateCategoryWithOptionsContext updates a category with options.
func (c *Client) UpdateCategoryWithOptionsContext(ctx context.Context, categoryID int64, categoryChanges *CategoryModificationRequest) (*Category, error) {
	body, err := c.request.Put(ctx, fmt.Sprintf("/v1/categories/%d", categoryID), categoryChanges)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var category *Category
	if err := json.NewDecoder(body).Decode(&category); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return category, nil
}

// MarkCategoryAsRead marks all unread entries in a category as read.
func (c *Client) MarkCategoryAsRead(categoryID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.MarkCategoryAsReadContext(ctx, categoryID)
}

// MarkCategoryAsReadContext marks all unread entries in a category as read.
func (c *Client) MarkCategoryAsReadContext(ctx context.Context, categoryID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/categories/%d/mark-all-as-read", categoryID), nil)
	return err
}

// CategoryFeeds returns all feeds for a category.
func (c *Client) CategoryFeeds(categoryID int64) (Feeds, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CategoryFeedsContext(ctx, categoryID)
}

// CategoryFeedsContext returns all feeds for a category.
func (c *Client) CategoryFeedsContext(ctx context.Context, categoryID int64) (Feeds, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/categories/%d/feeds", categoryID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var feeds Feeds
	if err := json.NewDecoder(body).Decode(&feeds); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return feeds, nil
}

// DeleteCategory removes a category.
func (c *Client) DeleteCategory(categoryID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.DeleteCategoryContext(ctx, categoryID)
}

// DeleteCategoryContext removes a category.
func (c *Client) DeleteCategoryContext(ctx context.Context, categoryID int64) error {
	return c.request.Delete(ctx, fmt.Sprintf("/v1/categories/%d", categoryID))
}

// RefreshCategory refreshes a category.
func (c *Client) RefreshCategory(categoryID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.RefreshCategoryContext(ctx, categoryID)
}

// RefreshCategoryContext refreshes a category.
func (c *Client) RefreshCategoryContext(ctx context.Context, categoryID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/categories/%d/refresh", categoryID), nil)
	return err
}

// Feeds gets all feeds.
func (c *Client) Feeds() (Feeds, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FeedsContext(ctx)
}

// FeedsContext gets all feeds.
func (c *Client) FeedsContext(ctx context.Context) (Feeds, error) {
	body, err := c.request.Get(ctx, "/v1/feeds")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var feeds Feeds
	if err := json.NewDecoder(body).Decode(&feeds); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return feeds, nil
}

// Export exports subscriptions as an OPML document.
func (c *Client) Export() ([]byte, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.ExportContext(ctx)
}

// ExportContext exports subscriptions as an OPML document.
func (c *Client) ExportContext(ctx context.Context) ([]byte, error) {
	body, err := c.request.Get(ctx, "/v1/export")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	opml, err := io.ReadAll(body)
	if err != nil {
		return nil, err
	}

	return opml, nil
}

// Import imports an OPML file.
func (c *Client) Import(f io.ReadCloser) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.ImportContext(ctx, f)
}

// ImportContext imports an OPML file.
func (c *Client) ImportContext(ctx context.Context, f io.ReadCloser) error {
	_, err := c.request.PostFile(ctx, "/v1/import", f)
	return err
}

// Feed gets a feed.
func (c *Client) Feed(feedID int64) (*Feed, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FeedContext(ctx, feedID)
}

// FeedContext gets a feed.
func (c *Client) FeedContext(ctx context.Context, feedID int64) (*Feed, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/feeds/%d", feedID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var feed *Feed
	if err := json.NewDecoder(body).Decode(&feed); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return feed, nil
}

// CreateFeed creates a new feed.
func (c *Client) CreateFeed(feedCreationRequest *FeedCreationRequest) (int64, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CreateFeedContext(ctx, feedCreationRequest)
}

// CreateFeedContext creates a new feed.
func (c *Client) CreateFeedContext(ctx context.Context, feedCreationRequest *FeedCreationRequest) (int64, error) {
	body, err := c.request.Post(ctx, "/v1/feeds", feedCreationRequest)
	if err != nil {
		return 0, err
	}
	defer body.Close()

	type result struct {
		FeedID int64 `json:"feed_id"`
	}

	var r result
	if err := json.NewDecoder(body).Decode(&r); err != nil {
		return 0, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return r.FeedID, nil
}

// UpdateFeed updates a feed.
func (c *Client) UpdateFeed(feedID int64, feedChanges *FeedModificationRequest) (*Feed, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateFeedContext(ctx, feedID, feedChanges)
}

// UpdateFeedContext updates a feed.
func (c *Client) UpdateFeedContext(ctx context.Context, feedID int64, feedChanges *FeedModificationRequest) (*Feed, error) {
	body, err := c.request.Put(ctx, fmt.Sprintf("/v1/feeds/%d", feedID), feedChanges)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var f *Feed
	if err := json.NewDecoder(body).Decode(&f); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return f, nil
}

// ImportFeedEntry imports a single entry into a feed.
func (c *Client) ImportFeedEntry(feedID int64, payload any) (int64, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()

	body, err := c.request.Post(
		ctx,
		fmt.Sprintf("/v1/feeds/%d/entries/import", feedID),
		payload,
	)
	if err != nil {
		return 0, err
	}
	defer body.Close()

	var response struct {
		ID int64 `json:"id"`
	}

	if err := json.NewDecoder(body).Decode(&response); err != nil {
		return 0, fmt.Errorf("miniflux: json error (%v)", err)
	}

	return response.ID, nil
}

// MarkFeedAsRead marks all unread entries of the feed as read.
func (c *Client) MarkFeedAsRead(feedID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.MarkFeedAsReadContext(ctx, feedID)
}

// MarkFeedAsReadContext marks all unread entries of the feed as read.
func (c *Client) MarkFeedAsReadContext(ctx context.Context, feedID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/feeds/%d/mark-all-as-read", feedID), nil)
	return err
}

// RefreshAllFeeds refreshes all feeds.
func (c *Client) RefreshAllFeeds() error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.RefreshAllFeedsContext(ctx)
}

// RefreshAllFeedsContext refreshes all feeds.
func (c *Client) RefreshAllFeedsContext(ctx context.Context) error {
	_, err := c.request.Put(ctx, "/v1/feeds/refresh", nil)
	return err
}

// RefreshFeed refreshes a feed.
func (c *Client) RefreshFeed(feedID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.RefreshFeedContext(ctx, feedID)
}

// RefreshFeedContext refreshes a feed.
func (c *Client) RefreshFeedContext(ctx context.Context, feedID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/feeds/%d/refresh", feedID), nil)
	return err
}

// ForceRefreshFeed refreshes a feed, bypassing the HTTP cache and reprocessing existing entries.
func (c *Client) ForceRefreshFeed(feedID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.ForceRefreshFeedContext(ctx, feedID)
}

// ForceRefreshFeedContext refreshes a feed, bypassing the HTTP cache and reprocessing existing entries.
func (c *Client) ForceRefreshFeedContext(ctx context.Context, feedID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/feeds/%d/refresh?force=true", feedID), nil)
	return err
}

// DeleteFeed removes a feed.
func (c *Client) DeleteFeed(feedID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.DeleteFeedContext(ctx, feedID)
}

// DeleteFeedContext removes a feed.
func (c *Client) DeleteFeedContext(ctx context.Context, feedID int64) error {
	return c.request.Delete(ctx, fmt.Sprintf("/v1/feeds/%d", feedID))
}

// FeedIcon gets a feed icon.
func (c *Client) FeedIcon(feedID int64) (*FeedIcon, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FeedIconContext(ctx, feedID)
}

// FeedIconContext gets a feed icon.
func (c *Client) FeedIconContext(ctx context.Context, feedID int64) (*FeedIcon, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/feeds/%d/icon", feedID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var feedIcon *FeedIcon
	if err := json.NewDecoder(body).Decode(&feedIcon); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return feedIcon, nil
}

// FeedEntry gets a single feed entry.
func (c *Client) FeedEntry(feedID, entryID int64) (*Entry, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FeedEntryContext(ctx, feedID, entryID)
}

// FeedEntryContext gets a single feed entry.
func (c *Client) FeedEntryContext(ctx context.Context, feedID, entryID int64) (*Entry, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/feeds/%d/entries/%d", feedID, entryID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var entry *Entry
	if err := json.NewDecoder(body).Decode(&entry); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return entry, nil
}

// CategoryEntry gets a single category entry.
func (c *Client) CategoryEntry(categoryID, entryID int64) (*Entry, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CategoryEntryContext(ctx, categoryID, entryID)
}

// CategoryEntryContext gets a single category entry.
func (c *Client) CategoryEntryContext(ctx context.Context, categoryID, entryID int64) (*Entry, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/categories/%d/entries/%d", categoryID, entryID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var entry *Entry
	if err := json.NewDecoder(body).Decode(&entry); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return entry, nil
}

// Entry gets a single entry.
func (c *Client) Entry(entryID int64) (*Entry, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.EntryContext(ctx, entryID)
}

// EntryContext gets a single entry.
func (c *Client) EntryContext(ctx context.Context, entryID int64) (*Entry, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/entries/%d", entryID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var entry *Entry
	if err := json.NewDecoder(body).Decode(&entry); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	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()
	defer cancel()
	return c.EntriesContext(ctx, filter)
}

// EntriesContext fetches entries.
func (c *Client) EntriesContext(ctx context.Context, filter *Filter) (*EntryResultSet, error) {
	path := buildFilterQueryString("/v1/entries", filter)

	body, err := c.request.Get(ctx, path)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var result EntryResultSet
	if err := json.NewDecoder(body).Decode(&result); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &result, nil
}

// FeedEntries fetches entries for a feed using the given filter.
func (c *Client) FeedEntries(feedID int64, filter *Filter) (*EntryResultSet, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FeedEntriesContext(ctx, feedID, filter)
}

// FeedEntriesContext fetches feed entries.
func (c *Client) FeedEntriesContext(ctx context.Context, feedID int64, filter *Filter) (*EntryResultSet, error) {
	path := buildFilterQueryString(fmt.Sprintf("/v1/feeds/%d/entries", feedID), filter)

	body, err := c.request.Get(ctx, path)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var result EntryResultSet
	if err := json.NewDecoder(body).Decode(&result); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &result, nil
}

// CategoryEntries fetches entries for a category using the given filter.
func (c *Client) CategoryEntries(categoryID int64, filter *Filter) (*EntryResultSet, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.CategoryEntriesContext(ctx, categoryID, filter)
}

// CategoryEntriesContext fetches category entries.
func (c *Client) CategoryEntriesContext(ctx context.Context, categoryID int64, filter *Filter) (*EntryResultSet, error) {
	path := buildFilterQueryString(fmt.Sprintf("/v1/categories/%d/entries", categoryID), filter)

	body, err := c.request.Get(ctx, path)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var result EntryResultSet
	if err := json.NewDecoder(body).Decode(&result); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &result, nil
}

// UpdateEntries updates the status of a list of entries.
func (c *Client) UpdateEntries(entryIDs []int64, status string) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateEntriesContext(ctx, entryIDs, status)
}

// UpdateEntriesContext updates the status of a list of entries.
func (c *Client) UpdateEntriesContext(ctx context.Context, entryIDs []int64, status string) error {
	type payload struct {
		EntryIDs []int64 `json:"entry_ids"`
		Status   string  `json:"status"`
	}

	_, err := c.request.Put(ctx, "/v1/entries", &payload{EntryIDs: entryIDs, Status: status})
	return err
}

// UpdateEntriesStarred updates the starred state of a list of entries.
func (c *Client) UpdateEntriesStarred(entryIDs []int64, starred bool) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateEntriesStarredContext(ctx, entryIDs, starred)
}

// UpdateEntriesStarredContext updates the starred state of a list of entries.
func (c *Client) UpdateEntriesStarredContext(ctx context.Context, entryIDs []int64, starred bool) error {
	type payload struct {
		EntryIDs []int64 `json:"entry_ids"`
		Starred  *bool   `json:"starred"`
	}

	_, err := c.request.Put(ctx, "/v1/entries", &payload{EntryIDs: entryIDs, Starred: &starred})
	return err
}

// UpdateEntry updates an entry.
func (c *Client) UpdateEntry(entryID int64, entryChanges *EntryModificationRequest) (*Entry, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateEntryContext(ctx, entryID, entryChanges)
}

// UpdateEntryContext updates an entry.
func (c *Client) UpdateEntryContext(ctx context.Context, entryID int64, entryChanges *EntryModificationRequest) (*Entry, error) {
	body, err := c.request.Put(ctx, fmt.Sprintf("/v1/entries/%d", entryID), entryChanges)
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var entry *Entry
	if err := json.NewDecoder(body).Decode(&entry); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return entry, nil
}

// ToggleStarred toggles the starred flag of an entry.
func (c *Client) ToggleStarred(entryID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.ToggleStarredContext(ctx, entryID)
}

// ToggleStarredContext toggles entry starred value.
func (c *Client) ToggleStarredContext(ctx context.Context, entryID int64) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/entries/%d/star", entryID), nil)
	return err
}

// SaveEntry sends an entry to a third-party service.
func (c *Client) SaveEntry(entryID int64) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.SaveEntryContext(ctx, entryID)
}

// SaveEntryContext sends an entry to a third-party service.
func (c *Client) SaveEntryContext(ctx context.Context, entryID int64) error {
	_, err := c.request.Post(ctx, fmt.Sprintf("/v1/entries/%d/save", entryID), nil)
	return err
}

// FetchEntryOriginalContent fetches the original content of an entry using the scraper.
func (c *Client) FetchEntryOriginalContent(entryID int64) (string, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FetchEntryOriginalContentContext(ctx, entryID)
}

// FetchEntryOriginalContentContext fetches the original content of an entry using the scraper.
func (c *Client) FetchEntryOriginalContentContext(ctx context.Context, entryID int64) (string, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/entries/%d/fetch-content", entryID))
	if err != nil {
		return "", err
	}
	defer body.Close()

	var response struct {
		Content string `json:"content"`
	}

	if err := json.NewDecoder(body).Decode(&response); err != nil {
		return "", fmt.Errorf("miniflux: response error (%v)", err)
	}

	return response.Content, nil
}

// FetchCounters fetches feed counters.
func (c *Client) FetchCounters() (*FeedCounters, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FetchCountersContext(ctx)
}

// FetchCountersContext fetches feed counters.
func (c *Client) FetchCountersContext(ctx context.Context) (*FeedCounters, error) {
	body, err := c.request.Get(ctx, "/v1/feeds/counters")
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var result FeedCounters
	if err := json.NewDecoder(body).Decode(&result); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return &result, nil
}

// FlushHistory deletes all entries with the status "read".
func (c *Client) FlushHistory() error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.FlushHistoryContext(ctx)
}

// FlushHistoryContext deletes all entries with the status "read".
func (c *Client) FlushHistoryContext(ctx context.Context) error {
	_, err := c.request.Put(ctx, "/v1/flush-history", nil)
	return err
}

// Icon fetches a feed icon.
func (c *Client) Icon(iconID int64) (*FeedIcon, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.IconContext(ctx, iconID)
}

// IconContext fetches a feed icon.
func (c *Client) IconContext(ctx context.Context, iconID int64) (*FeedIcon, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/icons/%d", iconID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var feedIcon *FeedIcon
	if err := json.NewDecoder(body).Decode(&feedIcon); err != nil {
		return nil, fmt.Errorf("miniflux: response error (%v)", err)
	}

	return feedIcon, nil
}

// Enclosure fetches a specific enclosure.
func (c *Client) Enclosure(enclosureID int64) (*Enclosure, error) {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.EnclosureContext(ctx, enclosureID)
}

// EnclosureContext fetches a specific enclosure.
func (c *Client) EnclosureContext(ctx context.Context, enclosureID int64) (*Enclosure, error) {
	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/enclosures/%d", enclosureID))
	if err != nil {
		return nil, err
	}
	defer body.Close()

	var enclosure *Enclosure
	if err := json.NewDecoder(body).Decode(&enclosure); err != nil {
		return nil, fmt.Errorf("miniflux: response error(%v)", err)
	}

	return enclosure, nil
}

// UpdateEnclosure updates an enclosure.
func (c *Client) UpdateEnclosure(enclosureID int64, enclosureUpdate *EnclosureUpdateRequest) error {
	ctx, cancel := withDefaultTimeout()
	defer cancel()
	return c.UpdateEnclosureContext(ctx, enclosureID, enclosureUpdate)
}

// UpdateEnclosureContext updates an enclosure.
func (c *Client) UpdateEnclosureContext(ctx context.Context, enclosureID int64, enclosureUpdate *EnclosureUpdateRequest) error {
	_, err := c.request.Put(ctx, fmt.Sprintf("/v1/enclosures/%d", enclosureID), enclosureUpdate)
	return err
}

func buildFilterQueryString(path string, filter *Filter) string {
	if filter != nil {
		values := url.Values{}

		if filter.Status != "" {
			values.Set("status", filter.Status)
		}

		if filter.Direction != "" {
			values.Set("direction", filter.Direction)
		}

		if filter.Order != "" {
			values.Set("order", filter.Order)
		}

		if filter.Limit >= 0 {
			values.Set("limit", strconv.Itoa(filter.Limit))
		}

		if filter.Offset >= 0 {
			values.Set("offset", strconv.Itoa(filter.Offset))
		}

		if filter.After > 0 {
			values.Set("after", strconv.FormatInt(filter.After, 10))
		}

		if filter.Before > 0 {
			values.Set("before", strconv.FormatInt(filter.Before, 10))
		}

		if filter.PublishedAfter > 0 {
			values.Set("published_after", strconv.FormatInt(filter.PublishedAfter, 10))
		}

		if filter.PublishedBefore > 0 {
			values.Set("published_before", strconv.FormatInt(filter.PublishedBefore, 10))
		}

		if filter.ChangedAfter > 0 {
			values.Set("changed_after", strconv.FormatInt(filter.ChangedAfter, 10))
		}

		if filter.ChangedBefore > 0 {
			values.Set("changed_before", strconv.FormatInt(filter.ChangedBefore, 10))
		}

		if filter.AfterEntryID > 0 {
			values.Set("after_entry_id", strconv.FormatInt(filter.AfterEntryID, 10))
		}

		if filter.BeforeEntryID > 0 {
			values.Set("before_entry_id", strconv.FormatInt(filter.BeforeEntryID, 10))
		}

		if filter.Starred != "" {
			values.Set("starred", filter.Starred)
		}

		if filter.Search != "" {
			values.Set("search", filter.Search)
		}

		if filter.CategoryID > 0 {
			values.Set("category_id", strconv.FormatInt(filter.CategoryID, 10))
		}

		if filter.FeedID > 0 {
			values.Set("feed_id", strconv.FormatInt(filter.FeedID, 10))
		}

		if filter.GloballyVisible {
			values.Set("globally_visible", "true")
		}

		for _, status := range filter.Statuses {
			values.Add("status", status)
		}

		for _, tag := range filter.Tags {
			values.Add("tags", tag)
		}

		path = fmt.Sprintf("%s?%s", path, values.Encode())
	}

	return path
}