# FreshRSS Integration Skill

This skill provides FreshRSS API integration for Clawd, allowing you to:
- Fetch RSS feeds from your FreshRSS server
- Process feed items with LLM analysis
- Monitor specific feeds for new content
- Create automated summaries of feed updates

## Configuration

You'll need to configure your FreshRSS credentials and API details:

Credentials are loaded from `~/.config/openclaw/freshrss/env`. See the `freshrss-reader` skill for the recommended secure setup.

```bash
# Create env file
mkdir -p ~/.config/openclaw/freshrss
cat > ~/.config/openclaw/freshrss/env << 'EOF'
FRESHRSS_URL=https://your-freshrss-instance.example.com
FRESHRSS_USER=your-username
FRESHRSS_API_PASSWORD=your-api-password
EOF
chmod 600 ~/.config/openclaw/freshrss/env
```

## Available Commands

### Fetch Latest Feeds
```
fetch latest feeds [hours:168]
```
Get the latest feed items from the past specified hours.

### Monitor Specific Feed
```
monitor feed [feed_id] [interval:60]
```
Continuously monitor a specific feed for new items.

### Summarize Feed Content
```
summarize feed [feed_id] [limit:10]
```
Get an LLM-generated summary of the latest feed items.

## Usage Examples

```
> fetch latest feeds
> monitor feed 123 300
> summarize feed 456
```

## Integration

This skill integrates with Clawd's session management and can:
- Run periodic checks via cron jobs
- Send notifications for new content
- Process feed items through your configured LLM models
- Store feed analysis results in workspace memory

## Security Notes

- API credentials are stored in configuration, not in code
- All API calls use HTTPS where available
- Feed content is processed locally before LLM analysis
- You can disable specific feeds or monitoring as needed

## API Notes

FreshRSS API is currently returning HTML redirects instead of JSON data. This suggests:
- API might be behind authentication
- Different endpoint format may be needed
- Feed IDs need to be verified

Current testing shows:
- HTTPS connection works (HTTP 200)
- But returns HTML instead of expected JSON
- May need to use `/i/api/` path prefix
- Authentication method might need adjustment

## Fever API Integration

FreshRSS also supports Fever API which might work better:
- API endpoint: `https://rss.hasbam.com.tr/api/fever.php`
- Authentication: MD5 hash of "username:apiPassword"
- Basic test: `curl -s -F "api_key=$api_key" 'https://rss.hasbam.com.tr/api/fever.php?api'`
- Expected result: `{ "api_version": 3, "auth": 1 }`

## Fever API Commands

Available Fever API actions:
- `feeds` - List all feeds
- `groups` - List categories
- `items` - List items (with filters)
- `unread_item_ids` - Get unread item IDs
- `saved_item_ids` - Get saved item IDs
- `mark=item&as=read` - Mark item as read
- `mark=item&as=unread` - Mark item as unread

## Testing Commands

```bash
# Test basic API
curl -s -F "api_key=$api_key" 'https://rss.hasbam.com.tr/api/fever.php?api'

# Get feeds
curl -s -F "api_key=$api_key" 'https://rss.hasbam.com.tr/api/fever.php?feeds'

# Get items
curl -s -F "api_key=$api_key" 'https://rss.hasbam.com.tr/api/fever.php?items'

# Mark item as read
curl -s -F "api_key=$api_key" 'https://rss.hasbam.com.tr/api/fever.php?mark=item&as=read&id=123'
```

## Debugging

If API doesn't work as expected:
1. Check fever.log for request details
2. Verify API key is correct MD5 hash
3. Test with Postman or curl first
4. Check FreshRSS user API password settings

## Google Reader API Integration

FreshRSS also supports Google Reader compatible API:
- API endpoint: `https://rss.hasbam.com.tr/api/greader.php`
- Authentication: GoogleLogin token
- Basic test: `curl -s -H "Authorization:GoogleLogin auth=$token" 'https://rss.hasbam.com.tr/api/greader.php/reader/api/0/subscription/list?output=json'`
- Expected result: JSON subscription list

## Google Reader API Commands

Available Google Reader API actions:
- `/accounts/ClientLogin` - Login and get token
- `/reader/api/0/subscription/list` - List subscriptions
- `/reader/api/0/unread-count` - Get unread counts
- `/reader/api/0/tag/list` - List tags
- `/reader/api/0/stream/contents/reading-list` - Get articles
- `/reader/api/0/subscription/edit` - Edit subscriptions

## Google Reader Authentication

```bash
# Get authentication token
curl -s -d "Email=alice&Passwd=Abcdef123456" 'https://rss.hasbam.com.tr/api/greader.php/accounts/ClientLogin'

# Use token for API calls
curl -s -H "Authorization:GoogleLogin auth=$token" 'https://rss.hasbam.com.tr/api/greader.php/reader/api/0/subscription/list?output=json'
```

## Testing Commands

```bash
# Test basic API
curl -s -H "Authorization:GoogleLogin auth=$token" 'https://rss.hasbam.com.tr/api/greader.php/reader/api/0/subscription/list?output=json'

# Get unread counts
curl -s -H "Authorization:GoogleLogin auth=$token" 'https://rss.hasbam.com.tr/api/greader.php/reader/api/0/unread-count?output=json'

# Get articles
curl -s -H "Authorization:GoogleLogin auth=$token" 'https://rss.hasbam.com.tr/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .
```

## Debugging

If Google Reader API doesn't work:
1. Verify token format and validity
2. Check HTTP headers and authentication
3. Test with different output formats
4. Check FreshRSS API access settings

## API Comparison

| API Type | Endpoint | Authentication | Features |
|----------|----------|----------------|----------|
| Basic | `/api/` | Basic auth | Limited |
| Fever | `/api/fever.php` | MD5 hash | Mobile clients |
| Google Reader | `/api/greader.php` | GoogleLogin | RSS clients |

## Recommendations

- Start with Fever API (most compatible with mobile apps)
- Use Google Reader API for desktop RSS clients
- Basic API may need additional configuration
- Test each API separately to find what works best