Initial commit

2026-04-18 09:03:18 +02:00
commit e03d7ea55c
16 changed files with 8174 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,183 @@
+# 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