184 lines
4.8 KiB
Markdown
184 lines
4.8 KiB
Markdown
# 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
|