freshrss/README.md

n8n-nodes-freshrss

Node społecznościowy dla n8n integrujący 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:

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

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

Budowanie

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

Linting i formatowanie

npm run lint
npm run format

Testy

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

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:

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:

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:

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:

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