n8n-nodes-ntfy-ext/README.md

n8n custom nodes for ntfy.sh integration (publish and subscribe/trigger) - extended

# n8n-nodes-ntfy-ext

n8n için ntfy.sh entegrasyon paketi. İki node içerir:
- Ntfy Send Message: Bir ntfy konusuna mesaj yayınlar (publish).
- Ntfy Trigger: Bir ntfy konusundan gelen mesajları dinler (SSE) ve iş akışını tetikler.

Kategori: Notifications

Referanslar:
- ntfy Publish API: https://docs.ntfy.sh/publish/
- ntfy Subscribe (SSE) API: https://docs.ntfy.sh/subscribe/
- ntfy Ana sayfa: https://ntfy.sh/

n8n uyumluluğu:
- Node türleri: Action (Send Message) ve Trigger (SSE).
- Inputs/Outputs:
  - Send Message: inputs=[main], outputs=[main].
  - Trigger: inputs=[], outputs=[main].
- Credentials yapısı: Bearer (API Key) ve Basic (Username/Password), n8n credentials sekmesiyle uyumlu.
- this.getNodeParameter, this.getCredentials ve this.helpers.returnJsonArray kullanım kalıpları n8n best practice ile uyumludur.
- Kategori: Notifications (n8n UI’de bu kategori altında görünür).

## Kurulum

```bash
npm install n8n-nodes-ntfy-ext
```

n8n kurulumunuzda bu paketi yükledikten sonra, n8n’i yeniden başlatın.

## Kimlik Doğrulama

Credentials: Ntfy API
- Auth Type:
  - API Key (Bearer)
  - Basic (Username & Password)
- Base URL: Varsayılan https://ntfy.sh

Not: Hem node parametresindeki baseUrl hem de credential’daki baseUrl kullanılabilir; node parametresi önceliklidir.

## Ntfy Send Message (Action Node)

Bir ntfy konusuna mesaj gönderir.

Zorunlu alanlar:
- Base URL (varsayılan: https://ntfy.sh)
- Topic
- Message

Opsiyonel alanlar (ntfy publish header’ları):
- Title
- Priority (1-5)
- Tags (virgülle ayrılmış)
- Click URL
- Actions (JSON)
- Attachment URL (attach)
- Filename
- Delay (örn: 30m, 1h, tomorrow)
- Email
- Call
- Cache (boolean)
- Firebase (boolean)
- Icon URL
- Markdown (boolean)
- Extra Headers (JSON)

Çalışma şekli:
- Mesaj gövdesi text/plain olarak gönderilir.
- Diğer alanlar ntfy header’ları şeklinde set edilir (X-Title, X-Priority, X-Tags, X-Actions, ...).
- Bearer/Basic Authorization header’ı otomatik oluşturulur (credentials varsa).

Çıktı: Başarılı gönderimde boş JSON: `{}`

## Ntfy Trigger (Trigger Node)

SSE kullanarak bir konuyu dinler ve her mesajı ayrı item olarak yayar.

Zorunlu alanlar:
- Base URL (varsayılan: https://ntfy.sh)
- Topic

Opsiyonel:
- Reconnect Delay (ms): Bağlantı koptuğunda yeniden bağlanma gecikmesi (varsayılan 2000ms)

Çalışma şekli:
- /topic/<name>/sse endpoint’i ile SSE akışı başlatılır.
- Akış kesildiğinde otomatik olarak retry yapılır.
- Gelen JSON event verisi ham haliyle item.json’a yazılır ve downstream node’lara iletilir.
- Workflow durdurulduğunda closeFunction ile bağlantı düzgün şekilde sonlandırılır.

Çıktı örneği:
```json
{
  "id": "string",
  "time": 1700000000,
  "event": "message",
  "topic": "my-topic",
  "title": "string",
  "message": "string",
  "priority": 3,
  "tags": ["tag1","tag2"],
  "click": "https://...",
  "actions": [],
  "attach": "https://...",
  "filename": "file.txt",
  "delay": "30m",
  "email": "x@y.z",
  "call": "+900000000",
  "cache": true,
  "firebase": false,
  "icon": "https://...",
  "up-time": 1700000000
}
```

## n8n’de Kurulum ve Ayar Örnek Kurgusu

Yükleme:
- n8n çalıştığı makinede terminalden:
  ```bash
  npm install n8n-nodes-ntfy-ext
  ```
- n8n’i yeniden başlatın (Desktop: uygulamayı kapat/aç; Self-hosted: servis/PM2/Docker restart).

n8n UI’de etkinleştirme:
- Settings → Community Nodes → Install → “n8n-nodes-ntfy-ext” yazın ve yükleyin.
- Güvenlik uyarısını onaylayın.

Credentials oluşturma (opsiyonel ama önerilir):
- Settings → Credentials → New → “Ntfy API”
  - Auth Type: Bearer (API Key) veya Basic
  - API Key veya Username/Password girin
  - Base URL: https://ntfy.sh (veya kendi ntfy sunucunuz)
  - Save

Örnek 1: Basit Publish Akışı
- Nodes:
  - Set: topic = "demo-topic", message = "Merhaba ntfy!"
  - Ntfy Send Message:
    - Base URL: https://ntfy.sh
    - Topic: {{$json.topic}}
    - Message: {{$json.message}}
    - Additional Options: Title = "Duyuru", Priority = 4, Tags = "info,ntfy"
    - Credentials: “Ntfy API” (Bearer/Basic)
- Çalıştırın; ntfy client’ında bildirimi görün.

Örnek 2: Trigger ile Otomasyon
- Nodes:
  - Ntfy Trigger:
    - Base URL: https://ntfy.sh
    - Topic: demo-topic
    - Reconnect Delay (ms): 2000
    - Credentials: “Ntfy API” (opsiyonel)
  - IF:
    - Condition: priority >= 4
  - Slack/E-mail node’u:
    - IF TRUE koluna bağlayın, kritik mesajları bildirin.
- Test:
  - Aşağıdaki curl ile mesaj yayınlayın:
    ```bash
    curl -H "X-Title: Kritik" -H "X-Priority: 5" -d "Sunucu hata verdi" https://ntfy.sh/demo-topic
    ```
  - Workflow tetiklenir, IF TRUE dalı çalışır.

Docker ile self-host n8n kullanımı:
- docker-compose.yml’de community nodes izinli olmalı. Örnek env:
  ```
  N8N_COMMUNITY_NODES_ENABLED=true
  ```
- Container içine girip paket kurabilir veya Host’ta volume ile node’u mount edebilirsiniz. Kurulum sonrası container’ı yeniden başlatın.

Sorun giderme:
- Publish HTTP hata kodları: Credentials ve topic/baseUrl değerlerini doğrulayın.
- Trigger akmıyor: Topic doğru mu, ntfy sunucusu erişilebilir mi, SSE engelleniyor mu (proxy/firewall)?
- Özel sunucu: Base URL sonuna slash koymayın; örn: https://ntfy.example.com
- Actions/Headers JSON: Geçerli JSON olduğundan emin olun.

## n8n İçinde Örnek Akışlar

1) Basit Publish Akışı
- Set node ile topic ve message belirleyin.
- Ntfy Send Message node’una bağlayın.
- Çalıştırın; ntfy mobil/desktop client üzerinden bildirimi görün.

2) Trigger ile Olay Tetikleme
- Ntfy Trigger node’unu ekleyin; baseUrl ve topic girin.
- Çıktıyı bir IF veya Switch node’una verip “priority” veya “tags” alanlarına göre dallandırın.
- Uygun durumda e-posta/Slack gibi aksiyon node’larına bağlayın.

## Geliştirme

Repo’yu klonladıktan sonra:

```bash
npm install
npm run build
```

Testler:
```bash
npm test
```

## Notlar
- Publish istekleri text/plain body ile yapılır, gelişmiş parametreler header olarak gönderilir.
- Trigger SSE bağlantısı hata durumunda otomatik yeniden bağlanır.
- ntfy publish/subscribe API referansları: https://docs.ntfy.sh/publish/ ve https://docs.ntfy.sh/subscribe/

Lisans: MIT