para-transferi 1.0.0

package/README.md

@@ -0,0 +1,799 @@
+# para-transferi
+
+**Uluslararası para transferi sağlayıcılarını karşılaştırma kütüphanesi** — Türkiye'den ve Türkiye'ye yapılan para transferlerinde en uygun sağlayıcıyı bulun.
+
+[![npm version](https://img.shields.io/npm/v/para-transferi.svg)](https://www.npmjs.com/package/para-transferi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-orange.svg)](https://www.npmjs.com/package/para-transferi)
+
+Wise, Remitly, XE, OFX, WorldRemit ve Revolut gibi popüler para transferi servislerinin **ücretlerini**, **döviz kurlarını**, **kur marjlarını** ve **transfer sürelerini** tek bir API ile karşılaştırın. Genişletilebilir plugin sistemi sayesinde banka, fintech veya yerel havale servisi gibi kendi sağlayıcılarınızı da ekleyebilirsiniz.
+
+---
+
+## Neden `para-transferi`?
+
+Uluslararası para transferi yaparken doğru sağlayıcıyı seçmek yüzlerce, hatta binlerce lira tasarruf ettirebilir. Ancak her sağlayıcının farklı ücret yapısı, kur marjı ve transfer hızı vardır. Bu kütüphane ile:
+
+- **Gerçek maliyeti görün** — Sadece transfer ücretini değil, gizli kur marjı maliyetini de hesaplayın
+- **Otomatik karşılaştırma yapın** — Tek bir fonksiyon çağrısıyla tüm sağlayıcıları sıralayın
+- **Uygulamanıza entegre edin** — Fintech uygulamaları, karşılaştırma siteleri veya kişisel projelerinize kolayca ekleyin
+- **Canlı döviz kurları ile çalışın** — ECB (Avrupa Merkez Bankası) verileriyle gerçek zamanlı hesaplama
+
+---
+
+## Özellikler
+
+| Özellik | Detay |
+|---------|-------|
+| **6 Yerleşik Sağlayıcı** | Wise, Remitly, XE, OFX, WorldRemit, Revolut |
+| **Canlı Döviz Kurları** | ECB ve exchangerate-api entegrasyonu, 30 dakika önbellek |
+| **Toplam Maliyet Hesaplama** | Transfer ücreti + kur marjı + koridor bazlı özel ücretler |
+| **Akıllı Karşılaştırma** | Maliyet, hız, puan veya kura göre sıralama |
+| **56 Ülke Desteği** | Türkiye, ABD, Almanya, İngiltere, Fransa ve 50+ ülke |
+| **46 Para Birimi** | TRY, USD, EUR, GBP, CHF ve 40+ para birimi |
+| **Plugin Sistemi** | Özel sağlayıcı ekleme, kaldırma ve güncelleme |
+| **TypeScript Desteği** | Tam tip tanımları, IntelliSense desteği |
+| **Sıfır Bağımlılık** | Node.js 18+ native `fetch()`, ek paket gerektirmez |
+| **Dual Format** | ESM ve CommonJS (CJS) çıktı desteği |
+
+---
+
+## Kurulum
+
+```bash
+npm install para-transferi
+```
+
+```bash
+# veya yarn ile
+yarn add para-transferi
+```
+
+```bash
+# veya pnpm ile
+pnpm add para-transferi
+```
+
+---
+
+## Hızlı Başlangıç
+
+### Sağlayıcıları Karşılaştır
+
+Türkiye'den Amerika'ya 10.000 TL göndermek isteyen bir kullanıcı için tüm sağlayıcıları karşılaştırın:
+
+```typescript
+import { karsilastir } from "para-transferi";
+
+const sonuc = await karsilastir({
+  gonderenUlke: "TR",
+  aliciUlke: "US",
+  gonderenParaBirimi: "TRY",
+  aliciParaBirimi: "USD",
+  miktar: 10000,
+});
+
+console.log(`Piyasa kuru: ${sonuc.piyasaKuru}`);
+console.log(`Kur kaynağı: ${sonuc.kurKaynagi}`);
+console.log(`Karşılaştırılan sağlayıcı sayısı: ${sonuc.sonuclar.length}`);
+
+// En ucuzdan en pahalıya sıralı sonuçlar
+for (const s of sonuc.sonuclar) {
+  console.log(`
+    ${s.saglayiciAd}
+    Transfer ücreti: ${s.transferUcreti} TRY
+    Kur marjı maliyeti: ${s.kurMarjiMaliyet} TRY
+    Toplam maliyet: ${s.toplamMaliyet} TRY
+    Alıcı alacak: ${s.aliciMiktar} USD
+    Tahmini süre: ${s.tahminiSure.aciklama}
+  `);
+}
+
+// Desteklemeyen sağlayıcıları da görebilirsiniz
+for (const d of sonuc.desteklemeyenler) {
+  console.log(`${d.saglayiciId}: ${d.sebep}`);
+}
+```
+
+### En Uygun Sağlayıcıyı Bul
+
+Tek satırda en düşük maliyetli sağlayıcıyı bulun:
+
+```typescript
+import { enUygun } from "para-transferi";
+
+const enIyi = await enUygun({
+  gonderenUlke: "TR",
+  aliciUlke: "DE",
+  gonderenParaBirimi: "TRY",
+  aliciParaBirimi: "EUR",
+  miktar: 5000,
+});
+
+if (enIyi) {
+  console.log(`En uygun sağlayıcı: ${enIyi.saglayiciAd}`);
+  console.log(`Toplam maliyet: ${enIyi.toplamMaliyet} TRY`);
+  console.log(`Alıcı alacak: ${enIyi.aliciMiktar} EUR`);
+  console.log(`Uygulanan kur: ${enIyi.uyguladigiKur}`);
+  console.log(`Piyasa kuru: ${enIyi.piyasaKuru}`);
+  console.log(`Kur marjı: %${enIyi.kurMarjiYuzde}`);
+}
+```
+
+### Tek Sağlayıcı ile Maliyet Hesapla
+
+Belirli bir sağlayıcının ücretlerini ayrıntılı hesaplayın:
+
+```typescript
+import { hesapla } from "para-transferi";
+
+const sonuc = await hesapla("wise", 10000, "TRY", "USD", "TR", "US");
+
+console.log(`Sağlayıcı: ${sonuc.saglayiciAd}`);
+console.log(`Gönderilen: ${sonuc.gonderenMiktar} ${sonuc.gonderenParaBirimi}`);
+console.log(`Alıcı alacak: ${sonuc.aliciMiktar} ${sonuc.aliciParaBirimi}`);
+console.log(`Transfer ücreti: ${sonuc.transferUcreti} TRY`);
+console.log(`Kur marjı maliyeti: ${sonuc.kurMarjiMaliyet} TRY`);
+console.log(`Toplam maliyet: ${sonuc.toplamMaliyet} TRY`);
+console.log(`Uygulanan kur: ${sonuc.uyguladigiKur}`);
+console.log(`Piyasa orta kuru: ${sonuc.piyasaKuru}`);
+console.log(`Tahmini süre: ${sonuc.tahminiSure.aciklama}`);
+```
+
+### Canlı Döviz Kuru Getir
+
+ECB veya exchangerate-api'den güncel döviz kurlarını çekin:
+
+```typescript
+import { kurGetir } from "para-transferi";
+
+const tryUsd = await kurGetir("TRY", "USD");
+console.log(`1 TRY = ${tryUsd.kur} USD`);
+console.log(`Kaynak: ${tryUsd.kaynak}`);
+console.log(`Tarih: ${tryUsd.tarih}`);
+
+const eurTry = await kurGetir("EUR", "TRY");
+console.log(`1 EUR = ${eurTry.kur} TRY`);
+```
+
+### Ülke ve Koridor Desteğini Kontrol Et
+
+Bir ülkenin hangi sağlayıcılar tarafından desteklendiğini öğrenin:
+
+```typescript
+import { ulkeDestegi, desteklenenUlkeler, desteklenenParaBirimleri } from "para-transferi";
+
+// Türkiye desteği
+const tr = ulkeDestegi("TR");
+console.log(`Ülke: ${tr.ulkeAdi}`);
+console.log(`Gönderi destekleyen: ${tr.destekleyenSaglayicilar.filter(s => s.gonderimVar).length} sağlayıcı`);
+console.log(`Alım destekleyen: ${tr.destekleyenSaglayicilar.filter(s => s.alimVar).length} sağlayıcı`);
+
+// Tüm desteklenen ülkeler
+const ulkeler = desteklenenUlkeler();
+console.log(`Toplam ${ulkeler.length} ülke destekleniyor`);
+
+// Tüm para birimleri
+const birimler = desteklenenParaBirimleri();
+console.log(`Toplam ${birimler.length} para birimi destekleniyor`);
+```
+
+### Sağlayıcıları Listele
+
+Kayıtlı tüm sağlayıcıların detaylı bilgilerine erişin:
+
+```typescript
+import { saglayicilar } from "para-transferi";
+
+const liste = saglayicilar();
+
+for (const s of liste) {
+  console.log(`
+    ${s.ad} (${s.id})
+    Web: ${s.webSitesi}
+    Kuruluş: ${s.kurulusYili}
+    Merkez: ${s.merkezUlke}
+    Puan: ${s.puan}/5
+    Kur marjı: %${s.kurMarjiYuzde}
+    Lisanslar: ${s.duzenleme.lisanslar.join(", ")}
+    Gönderen ülke sayısı: ${s.gonderenUlkeler.length}
+    Alıcı ülke sayısı: ${s.aliciUlkeler.length}
+    Ödeme yöntemleri: ${s.odemeYontemleri.join(", ")}
+  `);
+}
+```
+
+---
+
+## Desteklenen Sağlayıcılar
+
+### Wise (TransferWise)
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 2011, Londra |
+| Kur Marjı | %0 (orta piyasa kuru) |
+| Ücret Modeli | %0.4-%1.5 arası değişen ücretler |
+| Transfer Hızı | 30 dakika - 2 iş günü |
+| Lisanslar | FCA, FinCEN, ASIC, MAS |
+| Ödeme | Banka havalesi, kart, Apple Pay, Google Pay, SWIFT, SEPA |
+
+Wise, gerçek orta piyasa kurunu (mid-market rate) kullanan nadir sağlayıcılardan biridir. Kur marjı %0 olduğundan, toplam maliyet sadece transfer ücretinden oluşur. Özellikle büyük tutarlı transferlerde rekabetçi fiyatlar sunar.
+
+### Remitly
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 2011, Seattle |
+| Kur Marjı | ~%1.5 |
+| Ücret Modeli | Sabit ücret ($2.99 - $3.99) |
+| Transfer Hızı | Dakikalar (Express) - 5 iş günü (Economy) |
+| Lisanslar | FinCEN, FCA, ASIC |
+| Ödeme | Banka havalesi, banka kartı, kredi kartı |
+
+Remitly, gelişmekte olan ülkelere para gönderme konusunda uzmanlaşmıştır. Mobil cüzdan, nakit teslim ve eve teslim gibi alternatif teslimat seçenekleri sunar. Express seçeneğiyle dakikalar içinde para gönderebilirsiniz.
+
+### XE Money Transfer
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 1993, Kanada |
+| Kur Marjı | ~%1.0 |
+| Ücret Modeli | Transfer ücreti yok (maliyet kur marjına dahil) |
+| Transfer Hızı | 1-4 iş günü |
+| Lisanslar | FinCEN, FCA, ASIC, FINTRAC |
+| Ödeme | Banka havalesi, SWIFT |
+
+XE, dünyanın en bilinen döviz kuru platformudur. Transfer ücreti almaz ancak döviz kuru üzerinden marj uygular. Euronet Worldwide bünyesinde güvenilir ve köklü bir kurumdur.
+
+### OFX
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 1998, Sydney |
+| Kur Marjı | ~%0.4 |
+| Ücret Modeli | Transfer ücreti yok (maliyet kur marjına dahil) |
+| Transfer Hızı | 1-3 iş günü |
+| Lisanslar | ASIC, FCA, FinCEN, FINTRAC, MAS |
+| Ödeme | Banka havalesi, SWIFT |
+
+OFX, özellikle büyük tutarlı transferlerde (10.000$ ve üzeri) en rekabetçi kurları sunan sağlayıcıdır. %0.4 gibi düşük bir kur marjı ile işletmeler ve yüksek tutarlı bireysel transferler için idealdir. 5 milyon dolara kadar tek seferde transfer yapılabilir.
+
+### WorldRemit
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 2010, Londra |
+| Kur Marjı | ~%1.8 |
+| Ücret Modeli | Sabit ücret ($1.99 - $3.99) |
+| Transfer Hızı | Dakikalar (mobil cüzdan) - 3 iş günü |
+| Lisanslar | FCA, FinCEN, ASIC, FINTRAC |
+| Ödeme | Banka havalesi, banka kartı, kredi kartı, Apple Pay |
+
+WorldRemit, çoklu teslimat seçenekleriyle öne çıkar. M-Pesa gibi mobil cüzdanlara dakikalar içinde para gönderebilir, nakit teslim noktalarından para çektirebilirsiniz. Afrika ve Güney Asya'ya transferlerde popülerdir.
+
+### Revolut
+
+| Bilgi | Detay |
+|-------|-------|
+| Kuruluş | 2015, Londra |
+| Kur Marjı | ~%0.3 (hafta içi), ~%1.3 (hafta sonu) |
+| Ücret Modeli | Standart: aylık ücretsiz limit üzeri %0.5, Premium/Metal: sınırsız |
+| Transfer Hızı | Anlık (Revolut arası) - 3 iş günü (SWIFT) |
+| Lisanslar | ECB, FCA, FinCEN |
+| Ödeme | Banka havalesi, kart, Apple Pay, Google Pay, SWIFT, SEPA |
+
+Revolut, dijital bankacılık platformu olarak hafta içi neredeyse piyasa kuruna yakın kurlarla transfer sunar. Revolut kullanıcıları arasında anlık ve ücretsiz transfer yapılabilir. Premium ve Metal planlarında sınırsız ücretsiz döviz transferi bulunur.
+
+---
+
+## Sağlayıcı Karşılaştırma Tablosu
+
+| Sağlayıcı | Kur Marjı | Ücret | Min. Transfer | Maks. Transfer | Hız | Puan |
+|-----------|-----------|-------|---------------|----------------|-----|------|
+| **Wise** | %0 | %0.4-1.5 | $1 | $1.500.000 | 30dk-2 gün | 4.6/5 |
+| **Revolut** | %0.3 | %0-0.5 | $1 | $250.000 | Anlık-3 gün | 4.5/5 |
+| **Remitly** | %1.5 | $2.99-3.99 | $25 | $25.000 | Dakikalar-5 gün | 4.4/5 |
+| **OFX** | %0.4 | Yok | $250 | $5.000.000 | 1-3 gün | 4.3/5 |
+| **XE** | %1.0 | Yok | $100 | $500.000 | 1-4 gün | 4.2/5 |
+| **WorldRemit** | %1.8 | $1.99-3.99 | $10 | $10.000 | Dakikalar-3 gün | 4.1/5 |
+
+---
+
+## API Referansı
+
+### `karsilastir(parametreler)` — Sağlayıcıları Karşılaştır
+
+Belirtilen transfer koridoru ve miktar için tüm uygun sağlayıcıları karşılaştırır, maliyet hesabı yapar ve sıralar. Canlı döviz kuru ile çalışır.
+
+**Parametreler:**
+
+| Alan | Tip | Zorunlu | Varsayılan | Açıklama |
+|------|-----|---------|------------|----------|
+| `gonderenUlke` | `string` | Evet | — | Gönderen ülke kodu (ISO 3166-1 alpha-2, ör: `"TR"`) |
+| `aliciUlke` | `string` | Evet | — | Alıcı ülke kodu (ör: `"US"`, `"DE"`, `"GB"`) |
+| `gonderenParaBirimi` | `string` | Evet | — | Gönderen para birimi (ISO 4217, ör: `"TRY"`) |
+| `aliciParaBirimi` | `string` | Evet | — | Alıcı para birimi (ör: `"USD"`, `"EUR"`) |
+| `miktar` | `number` | Evet | — | Gönderilecek miktar (gönderen para birimi cinsinden) |
+| `siralamaKriteri` | `string` | Hayır | `"toplam_maliyet"` | Sıralama: `"toplam_maliyet"` \| `"hiz"` \| `"puan"` \| `"kur"` |
+| `saglayiciFiltresi` | `string[]` | Hayır | Tümü | Sadece belirli sağlayıcılar (ör: `["wise", "revolut"]`) |
+| `transferYontemi` | `string` | Hayır | Tümü | Filtre: `"banka_havalesi"` \| `"mobil_cuzdan"` \| `"nakit_teslim"` \| `"ev_teslim"` \| `"kart"` |
+
+**Dönen Değer:** `Promise<KarsilastirmaSonucu>`
+
+```typescript
+interface KarsilastirmaSonucu {
+  sorgu: KarsilastirmaParametreleri;   // Kullanılan parametreler
+  zamanDamgasi: string;                // ISO datetime
+  piyasaKuru: number;                  // Kullanılan piyasa orta kuru
+  kurKaynagi: string;                  // "ecb" veya "exchangerate_api"
+  sonuclar: TransferHesapSonucu[];     // Sıralı sağlayıcı sonuçları
+  desteklemeyenler: Array<{            // Bu koridoru desteklemeyen sağlayıcılar
+    saglayiciId: string;
+    sebep: string;
+  }>;
+}
+```
+
+### `hesapla(saglayiciId, miktar, gonderenParaBirimi, aliciParaBirimi, gonderenUlke?, aliciUlke?)` — Tek Sağlayıcı Hesapla
+
+Belirli bir sağlayıcı için ayrıntılı maliyet hesaplaması yapar.
+
+**Dönen Değer:** `Promise<TransferHesapSonucu>`
+
+```typescript
+interface TransferHesapSonucu {
+  saglayiciId: string;          // "wise"
+  saglayiciAd: string;          // "Wise (TransferWise)"
+  gonderenMiktar: number;       // 10000
+  gonderenParaBirimi: string;   // "TRY"
+  aliciMiktar: number;          // 285.50
+  aliciParaBirimi: string;      // "USD"
+  uyguladigiKur: number;        // Sağlayıcının uyguladığı kur
+  piyasaKuru: number;           // Gerçek piyasa orta kuru
+  kurMarjiYuzde: number;        // Kur marjı yüzdesi
+  kurMarjiMaliyet: number;      // Kur marjından kaynaklanan maliyet
+  transferUcreti: number;       // Transfer ücreti
+  toplamMaliyet: number;        // Toplam maliyet (ücret + kur marjı)
+  tahminiSure: {                // Transfer süresi
+    min: number;                // Minimum saat
+    maks: number;               // Maksimum saat
+    aciklama: string;           // "1 saat - 2 iş günü"
+  };
+  odemeYontemleri: string[];    // Desteklenen ödeme yöntemleri
+  puan: number;                 // Sağlayıcı puanı (1-5)
+}
+```
+
+### `kurGetir(kaynakParaBirimi, hedefParaBirimi)` — Döviz Kuru Getir
+
+ECB veya exchangerate-api'den canlı döviz kuru getirir. Sonuçlar 30 dakika önbelleklenir.
+
+**Dönen Değer:** `Promise<DovizKuru>`
+
+```typescript
+interface DovizKuru {
+  kaynak: string;              // "ecb" veya "exchangerate_api"
+  kaynakParaBirimi: string;    // "TRY"
+  hedefParaBirimi: string;     // "USD"
+  kur: number;                 // 0.02855
+  tarih: string;               // "2026-04-03"
+  zamanDamgasi: string;        // ISO datetime
+}
+```
+
+### `enUygun(parametreler)` — En Uygun Sağlayıcıyı Bul
+
+En düşük toplam maliyetli sağlayıcıyı döndürür. Parametreler `karsilastir()` ile aynıdır. Hiçbir sağlayıcı uygun değilse `null` döner.
+
+**Dönen Değer:** `Promise<TransferHesapSonucu | null>`
+
+### `saglayicilar()` — Sağlayıcıları Listele
+
+Kayıtlı tüm sağlayıcıların tam bilgilerini döndürür. Senkron fonksiyondur.
+
+**Dönen Değer:** `Saglayici[]`
+
+### `saglayiciEkle(saglayici)` — Yeni Sağlayıcı Ekle
+
+Plugin sistemiyle yeni sağlayıcı ekler. Aynı `id` ile eklenen sağlayıcı mevcut kaydı günceller.
+
+### `saglayiciKaldir(id)` — Sağlayıcı Kaldır
+
+Belirtilen sağlayıcıyı kayıttan kaldırır. Başarılıysa `true`, bulunamazsa `false` döner.
+
+### `ulkeDestegi(ulkeKodu)` — Ülke Desteği Kontrol Et
+
+Bir ülkenin hangi sağlayıcılar tarafından gönderim ve alım için desteklendiğini kontrol eder.
+
+### `desteklenenUlkeler()` — Tüm Ülkeleri Listele
+
+En az bir sağlayıcı tarafından desteklenen tüm ülkeleri döndürür.
+
+**Dönen Değer:** `Array<{ kod: string; ad: string }>`
+
+### `desteklenenParaBirimleri()` — Tüm Para Birimlerini Listele
+
+Sistemde tanımlı tüm para birimlerini döndürür.
+
+**Dönen Değer:** `Array<{ kod: string; ad: string; sembol: string }>`
+
+### `kurAyarla(ayarlar)` — Döviz Kuru Ayarları
+
+Kur kaynağı önceliğini, önbellek süresini ve API anahtarlarını yapılandırır.
+
+```typescript
+import { kurAyarla } from "para-transferi";
+
+kurAyarla({
+  onbellekSuresi: 3600,    // Önbellek süresi (saniye), varsayılan: 1800
+  kaynakOnceligi: ["exchangerate_api", "ecb"],  // Kaynak öncelik sırası
+  apiAnahtarlari: {
+    fixer: "API_ANAHTARINIZ",  // Opsiyonel ek kur kaynağı
+  },
+});
+```
+
+### `sifirla()` — Varsayılanlara Dön
+
+Tüm eklenen/kaldırılan sağlayıcıları sıfırlar, kur önbelleğini temizler ve 6 varsayılan sağlayıcıyı yeniden yükler.
+
+---
+
+## Plugin Sistemi — Özel Sağlayıcı Ekleme
+
+`para-transferi`'nin en güçlü özelliklerinden biri genişletilebilir plugin sistemidir. Herhangi bir bankayı, fintech'i veya yerel havale servisini kolayca ekleyebilirsiniz:
+
+```typescript
+import { saglayiciEkle, karsilastir } from "para-transferi";
+
+// Yerel bankanızı sağlayıcı olarak ekleyin
+saglayiciEkle({
+  id: "ziraat-bankasi",
+  ad: "Ziraat Bankası",
+  webSitesi: "https://www.ziraatbank.com.tr",
+  kurulusYili: 1863,
+  merkezUlke: "TR",
+  aciklama: "Türkiye'nin en büyük kamu bankası ile uluslararası havale",
+  gonderenUlkeler: ["TR"],
+  aliciUlkeler: ["US", "DE", "GB", "FR", "NL", "SA", "AE"],
+  gonderenParaBirimleri: ["TRY"],
+  aliciParaBirimleri: ["USD", "EUR", "GBP", "SAR", "AED"],
+  ucretYapisi: {
+    sabitUcret: 40,
+    sabitUcretParaBirimi: "TRY",
+    yuzdeUcret: 0.2,
+    minimumUcret: 40,
+    maksimumUcret: 500,
+    aciklama: "40 TL sabit + %0.2 komisyon, maks 500 TL",
+    koridorUcretleri: {
+      "TR_DE": { sabitUcret: 30 },  // Almanya'ya özel ücret
+    },
+  },
+  transferYontemleri: [
+    { tip: "banka_havalesi", ad: "SWIFT Havalesi", desteklenenUlkeler: [] },
+  ],
+  transferHizlari: [
+    {
+      yontem: "banka_havalesi",
+      minimumSaat: 24,
+      maksimumSaat: 72,
+      aciklama: "1-3 iş günü",
+    },
+  ],
+  limitler: {
+    minimumGonderim: 100,
+    maksimumGonderim: 500000,
+    paraBirimi: "TRY",
+    gunlukLimit: 500000,
+  },
+  kurMarjiYuzde: 2.5,
+  odemeYontemleri: ["banka_havalesi", "swift"],
+  puan: 3.8,
+  duzenleme: {
+    lisanslar: ["BDDK", "SPK"],
+    duzenleyiciUlkeler: ["TR"],
+  },
+});
+
+// Artık Ziraat Bankası da karşılaştırmada yer alır
+const sonuc = await karsilastir({
+  gonderenUlke: "TR",
+  aliciUlke: "DE",
+  gonderenParaBirimi: "TRY",
+  aliciParaBirimi: "EUR",
+  miktar: 20000,
+});
+
+console.log(`${sonuc.sonuclar.length} sağlayıcı karşılaştırıldı`);
+```
+
+---
+
+## Hata Yönetimi
+
+Paket, geliştirici deneyimini kolaylaştırmak için özel hata sınıfları kullanır. Her hata bir `kod` alanı içerir:
+
+```typescript
+import {
+  karsilastir,
+  ParaTransferiHatasi,
+  GecersizParametreHatasi,
+  SaglayiciBulunamadiHatasi,
+  KurGetirmeHatasi,
+} from "para-transferi";
+
+try {
+  const sonuc = await karsilastir({
+    gonderenUlke: "TR",
+    aliciUlke: "US",
+    gonderenParaBirimi: "TRY",
+    aliciParaBirimi: "USD",
+    miktar: 10000,
+  });
+} catch (hata) {
+  if (hata instanceof GecersizParametreHatasi) {
+    console.error("Geçersiz girdi:", hata.message);
+  } else if (hata instanceof KurGetirmeHatasi) {
+    console.error("Döviz kuru alınamadı:", hata.message);
+  } else if (hata instanceof ParaTransferiHatasi) {
+    console.error(`Hata [${hata.kod}]:`, hata.message);
+  }
+}
+```
+
+### Hata Sınıfları
+
+| Hata Sınıfı | Kod | Ne Zaman Fırlatılır |
+|-------------|-----|---------------------|
+| `ParaTransferiHatasi` | — | Tüm hataların temel sınıfı |
+| `GecersizParametreHatasi` | `GECERSIZ_PARAMETRE` | Geçersiz ülke kodu, para birimi veya miktar |
+| `SaglayiciBulunamadiHatasi` | `SAGLAYICI_BULUNAMADI` | `hesapla()` ile olmayan sağlayıcı ID'si kullanıldığında |
+| `KoridorDesteklenmiyorHatasi` | `KORIDOR_DESTEKLENMIYOR` | Gönderen-alıcı ülke kombinasyonu hiç desteklenmediğinde |
+| `KurGetirmeHatasi` | `KUR_GETIRME_HATASI` | ECB ve yedek kaynaklar da dahil tüm kur API'leri başarısız olduğunda |
+| `LimitAsimiHatasi` | `LIMIT_ASIMI` | Transfer miktarı sağlayıcının limitlerini aştığında |
+
+---
+
+## Desteklenen Ülkeler
+
+### Avrupa
+Türkiye (TR), Almanya (DE), Birleşik Krallık (GB), Fransa (FR), Hollanda (NL), Belçika (BE), Avusturya (AT), İsviçre (CH), İsveç (SE), Norveç (NO), Danimarka (DK), Finlandiya (FI), İtalya (IT), İspanya (ES), Portekiz (PT), Yunanistan (GR), Polonya (PL), Çekya (CZ), Macaristan (HU), Romanya (RO), Bulgaristan (BG), Hırvatistan (HR), İrlanda (IE)
+
+### Amerika
+Amerika Birleşik Devletleri (US), Kanada (CA), Brezilya (BR), Meksika (MX), Kolombiya (CO), Arjantin (AR), Şili (CL), Peru (PE)
+
+### Asya-Pasifik
+Japonya (JP), Çin (CN), Hindistan (IN), Pakistan (PK), Bangladeş (BD), Filipinler (PH), Malezya (MY), Singapur (SG), Tayland (TH), Endonezya (ID), Vietnam (VN), Güney Kore (KR), Avustralya (AU), Yeni Zelanda (NZ)
+
+### Orta Doğu ve Afrika
+Birleşik Arap Emirlikleri (AE), Suudi Arabistan (SA), İsrail (IL), Mısır (EG), Fas (MA), Nijerya (NG), Gana (GH), Kenya (KE), Güney Afrika (ZA)
+
+### Diğer
+Rusya (RU), Ukrayna (UA), Gürcistan (GE), Azerbaycan (AZ)
+
+---
+
+## Desteklenen Para Birimleri
+
+`TRY` Türk Lirası, `USD` Amerikan Doları, `EUR` Euro, `GBP` İngiliz Sterlini, `CHF` İsviçre Frangı, `SEK` İsveç Kronu, `NOK` Norveç Kronu, `DKK` Danimarka Kronu, `PLN` Polonya Zlotisi, `CZK` Çek Korunası, `HUF` Macar Forinti, `RON` Romen Leyi, `BGN` Bulgar Levası, `CAD` Kanada Doları, `AUD` Avustralya Doları, `NZD` Yeni Zelanda Doları, `JPY` Japon Yeni, `CNY` Çin Yuanı, `INR` Hindistan Rupisi, `PKR` Pakistan Rupisi, `BDT` Bangladeş Takası, `PHP` Filipin Pesosu, `MYR` Malezya Ringgiti, `SGD` Singapur Doları, `THB` Tayland Bahtı, `IDR` Endonezya Rupisi, `VND` Vietnam Dongu, `KRW` Güney Kore Wonu, `AED` BAE Dirhemi, `SAR` Suudi Riyali, `EGP` Mısır Lirası, `MAD` Fas Dirhemi, `NGN` Nijerya Nairası, `GHS` Gana Sedisi, `KES` Kenya Şilini, `ZAR` Güney Afrika Randı, `BRL` Brezilya Reali, `MXN` Meksika Pesosu, `COP` Kolombiya Pesosu, `ARS` Arjantin Pesosu, `CLP` Şili Pesosu, `PEN` Peru Solu, `ILS` İsrail Şekeli, `RUB` Rus Rublesi, `UAH` Ukrayna Grivnası, `GEL` Gürcistan Larisi, `AZN` Azerbaycan Manatı
+
+---
+
+## Popüler Transfer Koridorları
+
+Bu paket ile en sık kullanılan transfer rotalarını kolayca karşılaştırabilirsiniz:
+
+| Koridor | Açıklama |
+|---------|----------|
+| Türkiye → Almanya (TRY → EUR) | Almanya'daki Türk diasporasına para gönderimi |
+| Türkiye → ABD (TRY → USD) | Yurt dışı eğitim, iş ve aile transferleri |
+| Türkiye → İngiltere (TRY → GBP) | İngiltere'deki aileye havale |
+| Almanya → Türkiye (EUR → TRY) | Gurbetçi havaleleri |
+| ABD → Türkiye (USD → TRY) | Yurt dışından Türkiye'ye para gönderimi |
+| İngiltere → Türkiye (GBP → TRY) | İngiltere'den Türkiye'ye transfer |
+| Türkiye → Hollanda (TRY → EUR) | Hollanda'ya para transferi |
+| Türkiye → Fransa (TRY → EUR) | Fransa'ya para transferi |
+| Türkiye → Suudi Arabistan (TRY → SAR) | İşçi havaleleri |
+| Türkiye → BAE (TRY → AED) | Dubai ve Abu Dhabi'ye transfer |
+
+---
+
+## Kullanım Senaryoları
+
+### Fintech Uygulamaları
+
+Para transferi karşılaştırma özelliğini kendi uygulamanıza entegre edin:
+
+```typescript
+import { karsilastir, saglayiciEkle } from "para-transferi";
+
+// API endpoint'iniz
+app.get("/api/karsilastir", async (req, res) => {
+  const { gonderen, alici, paraBirimi, hedefParaBirimi, miktar } = req.query;
+
+  const sonuc = await karsilastir({
+    gonderenUlke: gonderen,
+    aliciUlke: alici,
+    gonderenParaBirimi: paraBirimi,
+    aliciParaBirimi: hedefParaBirimi,
+    miktar: Number(miktar),
+  });
+
+  res.json(sonuc);
+});
+```
+
+### Döviz Kuru Takip Botu
+
+```typescript
+import { kurGetir } from "para-transferi";
+
+const paraCiftleri = [
+  ["TRY", "USD"],
+  ["TRY", "EUR"],
+  ["TRY", "GBP"],
+  ["EUR", "USD"],
+];
+
+for (const [kaynak, hedef] of paraCiftleri) {
+  const kur = await kurGetir(kaynak, hedef);
+  console.log(`${kaynak}/${hedef}: ${kur.kur}`);
+}
+```
+
+### Maliyet Uyarı Sistemi
+
+```typescript
+import { enUygun } from "para-transferi";
+
+async function maliyetKontrol() {
+  const enIyi = await enUygun({
+    gonderenUlke: "TR",
+    aliciUlke: "DE",
+    gonderenParaBirimi: "TRY",
+    aliciParaBirimi: "EUR",
+    miktar: 10000,
+  });
+
+  if (enIyi && enIyi.toplamMaliyet < 200) {
+    console.log("Transfer maliyeti düşük, şimdi gönderme zamanı!");
+  }
+}
+```
+
+---
+
+## Maliyet Hesaplama Mantığı
+
+`para-transferi`'nin maliyet hesaplamasını anlamak, sonuçları doğru yorumlamanız için önemlidir:
+
+### Transfer Ücreti
+
+Her sağlayıcının ücret yapısı farklıdır:
+
+```
+transferÜcreti = max(minimumÜcret, sabitÜcret + (miktar × yüzdeÜcret / 100))
+
+// Maksimum ücret varsa:
+transferÜcreti = min(transferÜcreti, maksimumÜcret)
+```
+
+### Kur Marjı Maliyeti
+
+Bazı sağlayıcılar (Wise hariç) piyasa kurunun altında bir kur uygular:
+
+```
+uyguladigiKur = piyasaKuru × (1 - kurMarjıYüzde / 100)
+kurMarjıMaliyeti = miktar × (kurMarjıYüzde / 100)
+```
+
+### Toplam Maliyet
+
+```
+toplamMaliyet = transferÜcreti + kurMarjıMaliyeti
+```
+
+### Alıcı Miktar
+
+```
+alıcıMiktar = (miktar - transferÜcreti) × uyguladigiKur
+```
+
+> **Not:** Wise gibi %0 kur marjı uygulayan sağlayıcılarda toplam maliyet = transfer ücreti olur. OFX ve XE gibi transfer ücreti almayan sağlayıcılarda ise toplam maliyet = kur marjı maliyeti olur.
+
+---
+
+## Veri Kaynakları ve Güvenilirlik
+
+| Veri Tipi | Kaynak | Güncelleme |
+|-----------|--------|------------|
+| Döviz kurları | ECB (Avrupa Merkez Bankası) | Günlük (iş günleri) |
+| Yedek kur kaynağı | exchangerate-api.com | Gerçek zamanlı |
+| Sağlayıcı ücretleri | Resmi web siteleri | Paket güncellemeleriyle |
+| Sağlayıcı bilgileri | Resmi belgeler ve lisans kayıtları | Paket güncellemeleriyle |
+
+> **Uyarı:** Sağlayıcı ücretleri ve kur marjları zamanla değişebilir. Bu paket genel bir karşılaştırma aracıdır. Kesin tutarlar için transfer öncesinde sağlayıcının resmi sitesini kontrol edin.
+
+---
+
+## Sıkça Sorulan Sorular (SSS)
+
+### Bu paket gerçek para transferi yapıyor mu?
+
+Hayır. `para-transferi` yalnızca **karşılaştırma ve hesaplama** kütüphanesidir. Gerçek para transferi yapmaz, sağlayıcı API'lerine bağlanmaz. Transfer yapmak için sağlayıcıların kendi platformlarını kullanmanız gerekir.
+
+### Döviz kurları ne kadar güncel?
+
+ECB kurları her iş günü güncellenir. Paket içinde 30 dakikalık bir önbellek mekanizması vardır. `kurAyarla()` ile önbellek süresini değiştirebilirsiniz.
+
+### Kendi sağlayıcımı nasıl eklerim?
+
+`saglayiciEkle()` fonksiyonu ile `Saglayici` arayüzüne uygun bir obje geçirerek herhangi bir banka veya fintech servisini ekleyebilirsiniz. Detaylar için [Plugin Sistemi](#plugin-sistemi--özel-sağlayıcı-ekleme) bölümüne bakın.
+
+### Sağlayıcı verileri ne kadar doğru?
+
+Veriler sağlayıcıların resmi web sitelerinden derlenmiştir. Ancak ücret yapıları zaman içinde değişebilir. Kritik kararlar için transfer öncesi sağlayıcının güncel ücretlerini doğrulayın.
+
+### CommonJS projelerimde kullanabilir miyim?
+
+Evet. Paket hem ESM (`import`) hem CJS (`require`) formatını destekler:
+
+```javascript
+// ESM
+import { karsilastir } from "para-transferi";
+
+// CommonJS
+const { karsilastir } = require("para-transferi");
+```
+
+### Offline çalışır mı?
+
+Sağlayıcı listesi, ülke/para birimi verileri ve maliyet hesaplama mantığı offline çalışır. Ancak `karsilastir()`, `hesapla()` ve `kurGetir()` gibi canlı döviz kuru gerektiren fonksiyonlar internet bağlantısına ihtiyaç duyar.
+
+### Hangi Node.js versiyonları destekleniyor?
+
+Node.js 18 ve üstü. Paket native `fetch()` API'sini kullandığından Node.js 18+ gereklidir.
+
+---
+
+## Gereksinimler
+
+- **Node.js 18** veya üstü
+- İnternet bağlantısı (canlı kur fonksiyonları için)
+
+---
+
+## Lisans
+
+MIT License — Ticari ve kişisel projelerde serbestçe kullanabilirsiniz.
+
+## Katkıda Bulunma
+
+Katkılarınızı bekliyoruz!
+
+1. Bu repoyu fork edin
+2. Yeni bir branch oluşturun (`git checkout -b yeni-ozellik`)
+3. Değişikliklerinizi commit edin (`git commit -m "Yeni sağlayıcı eklendi"`)
+4. Branch'i push edin (`git push origin yeni-ozellik`)
+5. Pull Request oluşturun
+
+Büyük değişiklikler için önce bir issue açarak tartışmaya başlayın.
+
+---
+
+## İlgili Bağlantılar
+
+- [paratransferleri.com](https://paratransferleri.com) — Uluslararası para transferi karşılaştırma platformu
+- [Wise](https://wise.com) — Gerçek orta piyasa kuru ile transfer
+- [Remitly](https://www.remitly.com) — Hızlı uluslararası para transferi
+- [XE](https://www.xe.com) — Döviz kuru ve para transferi
+- [OFX](https://www.ofx.com) — Büyük tutarlı transferler
+- [WorldRemit](https://www.worldremit.com) — Çoklu teslimat seçenekleri
+- [Revolut](https://www.revolut.com) — Dijital bankacılık ve transfer
+
+---
+
+[paratransferleri.com](https://paratransferleri.com) tarafından geliştirilmiştir.