# n8n-nodes-freshrss

Node społecznościowy dla [n8n](https://n8n.io) integrujący [FreshRSS](https://freshrss.github.io/FreshRSS/) przez Google Reader API (GReader).

## Funkcjonalności

| Zasób | Operacja | Opis |
|---|---|---|
| **Kategoria** | Pobierz wszystkie | Lista wszystkich kategorii (etykiet) z instancji FreshRSS |
| **Artykuł** | Pobierz nieprzeczytane | Pobiera wszystkie nieprzeczytane artykuły ze wszystkich kanałów |
| **Artykuł** | Pobierz nieprzeczytane wg kategorii | Pobiera nieprzeczytane artykuły z wybranej kategorii |

Obie operacje artykułów obsługują **paginację** przez token kontynuacji oraz konfigurowalną **liczbę wyników** (1–1000).

## Wymagania

- Instancja FreshRSS z włączonym **Google Reader API**
  - Ustawienia → Uwierzytelnianie → Zezwól na dostęp przez API (zaznacz checkbox)
- **Hasło API** ustawione dla użytkownika
  - Ustawienia użytkownika → Uwierzytelnianie → Hasło API

## Instalacja

W instancji n8n:

```
Settings → Community Nodes → Install → n8n-nodes-freshrss
```

Lub przez npm w instalacji self-hosted:

```bash
npm install n8n-nodes-freshrss
```

## Dane uwierzytelniające

| Pole | Opis |
|---|---|
| Base URL | URL twojej instancji FreshRSS, np. `https://rss.example.com` |
| Username | Login do FreshRSS |
| API Password | Hasło API przypisane do użytkownika (Ustawienia → Uwierzytelnianie → Hasło API) — **różne** od hasła logowania |

## Parametry node'a

### Kategoria → Pobierz wszystkie

Zwraca wszystkie kategorie zdefiniowane przez użytkownika. Tagi systemowe (`com.google/*`) są automatycznie odfiltrowywane.

### Artykuł → Pobierz nieprzeczytane

Pobiera nieprzeczytane artykuły ze wszystkich kanałów.

| Parametr | Domyślnie | Opis |
|---|---|---|
| Maks. wyników | 50 | Maksymalna liczba artykułów (1–1000) |
| Token kontynuacji | — | Token paginacji zwrócony przez poprzednie wywołanie |

### Artykuł → Pobierz nieprzeczytane wg kategorii

Jak wyżej, ale ograniczone do jednej kategorii.

| Parametr | Domyślnie | Opis |
|---|---|---|
| Nazwa kategorii | — | Dokładna nazwa kategorii tak jak widnieje w FreshRSS |
| Maks. wyników | 50 | Maksymalna liczba artykułów (1–1000) |
| Token kontynuacji | — | Token paginacji zwrócony przez poprzednie wywołanie |

### Pola wyjściowe artykułu

```
id, title, author, published, updated, url,
content, feedTitle, feedUrl, categories,
isRead, isStarred
```

## Rozwój

### Konfiguracja środowiska

```bash
git clone https://github.com/paramah/n8n-nodes-freshrss
cd n8n-nodes-freshrss
npm install
```

### Budowanie

```bash
npm run build        # kompilacja TypeScript → dist/
npm run dev          # tryb obserwowania zmian
```

### Linting i formatowanie

```bash
npm run lint
npm run format
```

### Testy

Testy jednostkowe używają **Jest + ts-jest**. Nie wymagają instancji n8n — wszystkie wywołania HTTP są mockowane.

```bash
npm test                 # uruchom wszystkie testy
npm run test:watch       # tryb obserwowania zmian
npm run test:coverage    # z raportem pokrycia kodu
```

Zakres testów:

- `buildStreamUrl` — budowanie i enkodowanie URL
- `getAuthToken` — przepływ uwierzytelniania, obsługa błędów
- `freshrssApiRequest` — adapter HTTP, błędy 401/403
- `FreshRss.node` — wszystkie operacje, normalizacja artykułów, `continueOnFail`

### Ręczny runner CLI (bez n8n)

Testuj swoją instancję FreshRSS bezpośrednio z terminala, aby sprawdzić rzeczywisty output API.

**1. Skopiuj i uzupełnij dane uwierzytelniające:**

```bash
cp .env.test.example .env.test
# edytuj .env.test
```

`.env.test`:
```
FRESHRSS_URL=https://rss.example.com
FRESHRSS_USERNAME=twoj_login
FRESHRSS_API_PASSWORD=twoje_haslo_api
```

**2. Uruchom:**

```bash
npm run freshrss categories
npm run freshrss unread
npm run freshrss unread -- --max 10
npm run freshrss unread-by-category -- --category Tech
npm run freshrss unread-by-category -- --category Tech --max 5
npm run freshrss unread -- --continuation <token>
npm run freshrss unread -- --format json
```

Lub przez Task:

```bash
task categories
task unread
task unread-by-category CAT=Tech
task unread-by-category CAT=Tech MAX=5
```

Wynik można przekazać do `jq` z flagą `--format json`:

```bash
npm run freshrss unread -- --format json | jq '.[].title'
```

## Struktura projektu

```
src/
  credentials/
    FreshRssApi.credentials.ts   # definicja danych uwierzytelniających dla n8n
  nodes/
    FreshRss/
      FreshRss.node.ts           # główny node (zasoby, operacje, execute)
      helpers.ts                 # getAuthToken, freshrssApiRequest, buildStreamUrl
      freshrss.svg               # ikona node'a
      __tests__/
        helpers.test.ts          # testy jednostkowe helperów
        FreshRss.node.test.ts    # testy jednostkowe node'a
scripts/
  freshrss-run.ts                # standalone runner CLI
```

## Licencja

MIT