# FreshRSS List Widget for Homepage

A custom widget for [gethomepage.dev](https://gethomepage.dev) that displays the latest RSS feed items from your [FreshRSS](https://freshrss.org/) subscriptions.

## Why?

The built-in FreshRSS widget for Homepage only shows the **unread count**. This widget goes a step further by listing the actual articles from your reading list (or a specific category) directly on your dashboard.

## Features

- Lists recent RSS items with title, date, author, and source feed.
- Supports filtering by FreshRSS category/label.
- Configurable number of items to display.
- Links directly to the article.

## Prerequisites

- A running FreshRSS instance with the **Google Reader API** enabled.
  - In FreshRSS: **Settings → Profile → API management** → Enable API and set your API password.
  - Ensure the Google Reader API endpoint (`api/greader.php`) is accessible.

## Installation

1. Copy the `freshrsslist` folder into your Homepage widgets directory (e.g., `src/widgets/` or your custom widgets path).
2. If Homepage requires widget registration, import and add it to your widget registry.

## Configuration

Add the widget to your `services.yaml` (or `widgets.yaml`):

```yaml
- FreshRSS:
    href: https://your-freshrss-instance.com
    widget:
      type: freshrsslist
      url: https://your-freshrss-instance.com
      username: your_username
      password: your_api_password  # Not your regular login password
      category: Tech # Optional: filter by FreshRSS label
      limit: 5       # Optional: number of items (default: 5)
```

## Options
| Field      | Required | Description |
|------------|----------|------------------------------------------------------------------------|
| `url`      | Yes      | Base URL of your FreshRSS instance.                                    |
| `username` | Yes      | Your FreshRSS username.                                                |
| `password` | Yes      | Your FreshRSS **API password** (set in Profile → API management).      |
| `category` | No       | A FreshRSS category/label to filter items. Omit to show reading list.  |
| `limit`    | No       | Number of items to display. Default: `5`.                              |

## How It Works
      
The widget authenticates with FreshRSS via the Google Reader API (`ClientLogin`) and fetches the stream contents. It then maps the API response to a clean list of articles rendered inside a Homepage service container.
      
## File Structure
      
- `widget.js` — Defines the widget endpoint and proxy handler.
- `proxy.js` — Handles FreshRSS authentication and API requests.
- `components.jsx` — The React component that renders the RSS list.
      
## License
MIT