@yildizpay/http-adapter 3.0.0 → 3.1.0

package/README.md

@@ -11,6 +11,7 @@ A professional, robust, and highly configurable HTTP client adapter designed for
 ## Key Features
 
 - **Fluent Request Builder:** Construct complex HTTP requests with an intuitive, chainable API.
+- **Structured Exception Hierarchy:** Every HTTP status code and network failure maps to a dedicated, named exception class with rich metadata, `isRetryable()` signals, and structured `toJSON()` serialization.
 - **Interceptor Architecture:** Easily implement middleware for logging, authentication, error handling, and data transformation.
 - **Resilience & Reliability:** Built-in support for retry policies (Exponential Backoff, etc.) and a generic **Circuit Breaker** to handle transient failures gracefully and prevent cascading failures in S2S communication.
 - **Type Safety:** Fully typed requests and responses using generics, ensuring type safety across your application.
@@ -53,7 +54,7 @@ import { HttpAdapter, RetryPolicies, CircuitBreaker } from '@yildizpay/http-adap
 
 const circuitBreaker = new CircuitBreaker({
   failureThreshold: 5,
-  resetTimeoutMs: 60000, 
+  resetTimeoutMs: 60000,
 });
 
 const adapter = HttpAdapter.create(
@@ -62,7 +63,7 @@ const adapter = HttpAdapter.create(
   ],
   RetryPolicies.exponential(3), // Retry up to 3 times with exponential backoff
   undefined,                    // Optional custom HTTP client
-  circuitBreaker                // Optional Circuit Breaker
+  circuitBreaker,               // Optional Circuit Breaker
 );
 ```
 
@@ -84,6 +85,175 @@ try {
 }
 ```
 
+## Error Handling
+
+`@yildizpay/http-adapter` converts every raw error — HTTP failures, network-level OS errors, or totally unexpected exceptions — into a structured, typed exception class. This means your `catch` blocks never need to inspect raw status codes or error codes manually.
+
+### Exception Hierarchy
+
+```
+BaseAdapterException
+├── HttpException                    (any HTTP response error)
+│   ├── BadRequestException          (400)
+│   ├── UnauthorizedException        (401)
+│   ├── ForbiddenException           (403)
+│   ├── NotFoundException            (404)
+│   ├── ConflictException            (409)
+│   ├── UnprocessableEntityException (422)
+│   ├── TooManyRequestsException     (429)  ← isRetryable() = true
+│   ├── InternalServerErrorException (500)
+│   ├── BadGatewayException          (502)  ← isRetryable() = true
+│   ├── ServiceUnavailableException  (503)  ← isRetryable() = true
+│   ├── GatewayTimeoutException      (504)  ← isRetryable() = true
+│   └── ... (all 4xx / 5xx codes)
+├── NetworkException                 (OS-level connectivity failures)
+│   ├── ConnectionRefusedException   (ECONNREFUSED)  ← isRetryable() = true
+│   ├── TimeoutException             (ETIMEDOUT / ECONNABORTED / AbortError)  ← isRetryable() = true
+│   ├── SocketResetException         (ECONNRESET)  ← isRetryable() = true
+│   ├── DnsResolutionException       (ENOTFOUND / EAI_AGAIN)
+│   └── HostUnreachableException     (EHOSTUNREACH / ENETUNREACH)
+├── UnknownException                 (any unclassifiable error)
+└── CircuitBreakerOpenException      (circuit is open, request not sent)
+```
+
+### Catching Exceptions by Type
+
+```typescript
+import {
+  NotFoundException,
+  TooManyRequestsException,
+  TimeoutException,
+  ConnectionRefusedException,
+  CircuitBreakerOpenException,
+  UnknownException,
+} from '@yildizpay/http-adapter';
+
+try {
+  const response = await adapter.send<PaymentResponse>(request);
+} catch (error) {
+  if (error instanceof NotFoundException) {
+    // HTTP 404 — resource does not exist
+    console.error('Resource not found:', error.response.data);
+  } else if (error instanceof TooManyRequestsException) {
+    // HTTP 429 — back off before retrying
+    const retryAfterMs = error.getRetryAfterMs();
+    console.warn(`Rate limited. Retry after ${retryAfterMs}ms`);
+  } else if (error instanceof TimeoutException) {
+    // ETIMEDOUT / AbortError — downstream service too slow
+    console.error('Request timed out:', error.code);
+  } else if (error instanceof ConnectionRefusedException) {
+    // ECONNREFUSED — downstream service is down
+    console.error('Service is down:', error.requestContext?.url);
+  } else if (error instanceof CircuitBreakerOpenException) {
+    // Circuit is open — fail fast without hitting the server
+    console.error('Circuit breaker is open. Not sending request.');
+  } else if (error instanceof UnknownException) {
+    // Something unexpected — log and investigate
+    console.error('Unhandled error:', error.toJSON());
+  }
+}
+```
+
+### Type Guards
+
+If you prefer narrowing without `instanceof` (useful in functional pipelines or when crossing module boundaries), every exception class has a corresponding type guard:
+
+```typescript
+import {
+  isHttpException,
+  isTimeoutException,
+  isConnectionRefusedException,
+  isCircuitBreakerOpenException,
+} from '@yildizpay/http-adapter';
+
+function handleError(error: unknown): void {
+  if (isTimeoutException(error)) {
+    // TypeScript now knows: error is TimeoutException
+    scheduleRetry(error.requestContext?.url);
+  } else if (isHttpException(error)) {
+    // TypeScript now knows: error is HttpException
+    reportToMonitoring(error.response.status, error.response.data);
+  }
+}
+```
+
+### `isRetryable()` Signal
+
+Each exception exposes an `isRetryable(): boolean` method that reflects whether the failure is transient and worth retrying. This is useful when implementing custom retry decorators or deciding at the application layer whether to propagate or retry an error.
+
+```typescript
+} catch (error) {
+  if (error instanceof BaseAdapterException && error.isRetryable()) {
+    return retryOperation();
+  }
+  throw error;
+}
+```
+
+Retryable exceptions: `TooManyRequestsException (429)`, `BadGatewayException (502)`, `ServiceUnavailableException (503)`, `GatewayTimeoutException (504)`, `TimeoutException`, `SocketResetException`, `ConnectionRefusedException`.
+
+### Structured Logging with `toJSON()`
+
+All exceptions override `toJSON()`, making them compatible with structured loggers (Pino, Winston, etc.). `JSON.stringify(error)` produces a complete, nested log entry instead of an empty `{}`.
+
+```typescript
+} catch (error) {
+  if (error instanceof BaseAdapterException) {
+    logger.error(error.toJSON());
+    // {
+    //   name: 'NotFoundException',
+    //   message: 'Not Found',
+    //   code: 'ERR_NOT_FOUND',
+    //   stack: '...',
+    //   response: {
+    //     status: 404,
+    //     data: { detail: 'Payment record not found' },
+    //     request: { method: 'GET', url: 'https://api.example.com/payments/123', correlationId: 'corr-abc' }
+    //   }
+    // }
+  }
+}
+```
+
+### `RequestContext` — Safe Request Metadata
+
+Every exception automatically carries a `RequestContext` object (`method`, `url`, `correlationId`) sourced from the originating request. Headers and body are deliberately excluded to prevent accidental auth-token or PII leakage in logs.
+
+```typescript
+} catch (error) {
+  if (error instanceof NetworkException) {
+    logger.warn({
+      event: 'network_failure',
+      exception: error.name,
+      request: error.requestContext, // { method, url, correlationId }
+    });
+  }
+}
+```
+
+### Error Interceptor
+
+You can also catch and transform exceptions at the interceptor layer before they reach your business logic.
+
+```typescript
+import {
+  HttpErrorInterceptor,
+  Request,
+  BaseAdapterException,
+  UnauthorizedException,
+} from '@yildizpay/http-adapter';
+
+export class GlobalErrorInterceptor implements HttpErrorInterceptor {
+  async onError(error: BaseAdapterException, request: Request): Promise<never> {
+    if (error instanceof UnauthorizedException) {
+      await this.tokenService.refresh();
+    }
+    // Re-throw so the caller can handle it
+    throw error;
+  }
+}
+```
+
 ## Resilience & Retries
 
 Network instability is inevitable. This adapter allows you to define robust retry strategies.
@@ -95,7 +265,7 @@ The built-in `ExponentialBackoffPolicy` waits increasingly longer between retrie
 ```typescript
 import { RetryPolicies } from '@yildizpay/http-adapter';
 
-// Retries on 429, 500, 502, 503, 504 and network errors
+// Retries on 429, 502, 503, 504 and network errors
 const retryPolicy = RetryPolicies.exponential(5);
 ```
 
@@ -118,6 +288,7 @@ const breaker = new CircuitBreaker({
 Thanks to the **Interface Segregation Principle (ISP)**, you aren't forced to implement massive interfaces. You can hook into the exact lifecycle event you need by implementing `HttpRequestInterceptor`, `HttpResponseInterceptor`, or `HttpErrorInterceptor`.
 
 ### 1. Request Interceptor (e.g., Auth Tokens)
+
 Add common headers like Authorization tokens before requests leave.
 
 ```typescript
@@ -132,6 +303,7 @@ export class AuthInterceptor implements HttpRequestInterceptor {
 ```
 
 ### 2. Response Interceptor (e.g., Data Transformation)
+
 Inspect or mutate payloads identically across all incoming responses.
 
 ```typescript
@@ -140,7 +312,7 @@ import { HttpResponseInterceptor, Response } from '@yildizpay/http-adapter';
 export class TransformResponseInterceptor implements HttpResponseInterceptor {
   async onResponse(response: Response): Promise<Response> {
     if (response.status === 201) {
-       console.log('Resource successfully created!');
+      console.log('Resource successfully created!');
     }
     return response;
   }
@@ -148,17 +320,22 @@ export class TransformResponseInterceptor implements HttpResponseInterceptor {
 ```
 
 ### 3. Error Interceptor (e.g., Global Error Handling)
+
 Catch network failures or non-success HTTP statuses centrally.
 
 ```typescript
-import { HttpErrorInterceptor, Request, HttpClientException } from '@yildizpay/http-adapter';
+import {
+  HttpErrorInterceptor,
+  Request,
+  BaseAdapterException,
+  UnauthorizedException,
+} from '@yildizpay/http-adapter';
 
 export class GlobalErrorInterceptor implements HttpErrorInterceptor {
-  async onError(error: unknown, request: Request): Promise<unknown> {
-    if (error instanceof HttpClientException && error.response?.status === 401) {
-       console.error(`Unauthorized access to ${request.endpoint}! Redirecting to login...`);
+  async onError(error: BaseAdapterException, request: Request): Promise<BadRequestException> {
+    if (error instanceof UnauthorizedException) {
+      console.error(`Unauthorized access to ${error.requestContext?.url}! Redirecting to login...`);
     }
-    // You can throw a custom error or return a fallback payload
     throw error;
   }
 }

package/README.tr.md

@@ -6,16 +6,17 @@
 ![NPM Version](https://img.shields.io/npm/v/@yildizpay/http-adapter)
 ![License](https://img.shields.io/npm/l/@yildizpay/http-adapter)
 
-Node.js tabanlı kurumsal seviye (enterprise-grade) uygulamalar için tasarlanmış profesyonel, dayanıklı (robust) ve yüksek oranda yapılandırılabilir bir HTTP istemci (client) adaptörü. Akıcı (fluent) bir API, yerleşik ağ direnci (resilience) desenleri ve güçlü bir önleyici (interceptor) sistemi sunar. Dış bağımlılık bulundurmayan (zero-dependency) paketin çekirdeği **Node.js Native Fetch API** kullanır ancak tercih edilen farklı özel HTTP istemcilerine de (Custom Clients) kolayca genişletilebilir.
+Node.js tabanlı kurumsal uygulamalar için tasarlanmış profesyonel ve yüksek oranda yapılandırılabilir bir HTTP client adaptörü. Fluent API, built-in resilience pattern'ları, güçlü bir interceptor sistemi ve kapsamlı bir exception hiyerarşisi sunar. Zero-dependency olan paketin çekirdeği **Node.js Native Fetch API** kullanır; ancak istenen farklı custom HTTP client'lara da kolayca genişletilebilir.
 
 ## Temel Özellikler
 
-- **Akıcı İstek Oluşturucu (Fluent Request Builder):** Sezgisel ve zincirlenebilir (chainable) bir API ile karmaşık HTTP isteklerini kolayca oluşturun.
-- **Önleyici Mimarisi (Interceptor Architecture):** Loglama, kimlik doğrulama, hata yönetimi ve veri dönüşümü gibi ara yazılım (middleware) işlemlerini zahmetsizce entegre edin.
-- **Ağ Direnci ve Güvenilirlik (Resilience & Reliability):** Sunucular arası entegrasyonlarda geçici arızaları zarif bir şekilde yönetmek ve zincirleme (cascading) hataları önlemek için üstel geri çekilme (Exponential Backoff vs.) gibi yeniden deneme (retry) politikaları ve yerleşik bir **Devre Kesici (Circuit Breaker)** içerir.
-- **Tip Güvenliği (Type Safety):** Jenerikleri (generics) kullanan tam tiplendirilmiş (fully typed) istek ve yanıtlar ile uygulamanız genelinde tip güvenliği sağlar.
-- **Test Edilebilirlik:** Bağımlılık enjeksiyonu (dependency injection) düşünülerek tasarlandığından, birim testleri (unit mock) yazmak oldukça kolaydır.
-- **Değişmez (Immutable) Tasarım:** Eşzamanlı (concurrent) ortamlarda yan etkileri (side effects) önlemek için çekirdek (core) bileşenler değiştirilemez (immutable) yapıda tasarlanmıştır.
+- **Fluent Request Builder:** Sezgisel ve zincirlenebilir bir API ile karmaşık HTTP isteklerini kolayca oluşturun.
+- **Structured Exception Hierarchy:** Her HTTP durum kodu ve ağ hatası, zengin metadata, `isRetryable()` sinyali ve `toJSON()` desteğiyle ayrı bir exception sınıfına dönüştürülür.
+- **Interceptor Mimarisi:** Loglama, kimlik doğrulama, hata yönetimi ve veri dönüşümü gibi middleware işlemlerini zahmetsizce entegre edin.
+- **Resilience & Reliability:** S2S entegrasyonlarında geçici hataları zarif bir şekilde yönetmek için Exponential Backoff gibi retry policy'ler ve built-in **Circuit Breaker** içerir.
+- **Type Safety:** Generic'ler kullanılarak tam olarak tiplendirilmiş request ve response'lar ile uygulama genelinde tip güvenliği sağlanır.
+- **Test Edilebilirlik:** Dependency injection düşünülerek tasarlandığından mock yazmak oldukça kolaydır.
+- **Immutable Tasarım:** Concurrent ortamlarda side effect'leri önlemek için core bileşenler immutable olarak tasarlanmıştır.
 
 ## Kurulum
 
@@ -29,9 +30,9 @@ pnpm add @yildizpay/http-adapter
 
 ## Kullanım
 
-### 1. Temel İstek Oluşturma
+### 1. Request Oluşturma
 
-İstekleri temiz ve öz bir şekilde oluşturmak için `RequestBuilder` sınıfını kullanın.
+`RequestBuilder` ile istekleri temiz ve öz bir şekilde oluşturun.
 
 ```typescript
 import { RequestBuilder, HttpMethod } from '@yildizpay/http-adapter';
@@ -44,31 +45,31 @@ const request = new RequestBuilder('https://api.example.com')
   .build();
 ```
 
-### 2. Adaptörü Başlatma
+### 2. Adapter'ı Başlatma
 
-İsteğe bağlı önleyiciler (interceptors), yeniden deneme (retry) politikaları ve devre kesici (circuit breaker) ile `HttpAdapter` nesnesini oluşturun.
+İsteğe bağlı interceptor'lar, retry policy ve circuit breaker ile `HttpAdapter` oluşturun.
 
 ```typescript
 import { HttpAdapter, RetryPolicies, CircuitBreaker } from '@yildizpay/http-adapter';
 
 const circuitBreaker = new CircuitBreaker({
   failureThreshold: 5,
-  resetTimeoutMs: 60000, 
+  resetTimeoutMs: 60000,
 });
 
 const adapter = HttpAdapter.create(
   [
-    /* interceptors (önleyiciler) */
+    /* interceptors */
   ],
-  RetryPolicies.exponential(3), // Üstel (exponential) geri çekilme ile 3 defaya kadar yeniden dene
-  undefined,                    // İsteğe bağlı özel HTTP istemcisi (opsiyonel)
-  circuitBreaker                // İsteğe bağlı Devre Kesici (opsiyonel)
+  RetryPolicies.exponential(3), // Exponential backoff ile 3 defaya kadar retry
+  undefined,                    // Opsiyonel custom HTTP client
+  circuitBreaker,               // Opsiyonel Circuit Breaker
 );
 ```
 
-### 3. İstek Gönderme
+### 3. Request Gönderme
 
-İsteği yürütün ve kesin bir şekilde tiplendirilmiş (strongly-typed) yanıtı (response) alın.
+Request'i çalıştırın ve strongly-typed response alın.
 
 ```typescript
 interface UserResponse {
@@ -80,45 +81,215 @@ try {
   const response = await adapter.send<UserResponse>(request);
   console.log('Kullanıcı oluşturuldu:', response.data);
 } catch (error) {
-  console.error('İstek başarısız oldu:', error);
+  console.error('Request başarısız oldu:', error);
 }
 ```
 
-## Direnç ve Yeniden Denemeler (Resilience & Retries)
+## Hata Yönetimi (Error Handling)
 
-Ağ kararsızlığı kaçınılmazdır. Bu adaptör, sağlam yeniden deneme stratejileri tanımlamanıza olanak tanır.
+`@yildizpay/http-adapter`, her türlü ham hatayı — HTTP hataları, OS düzeyindeki ağ hataları veya tamamen beklenmedik exception'lar — yapılandırılmış ve tiplendirilmiş bir exception sınıfına dönüştürür. Bu sayede `catch` bloklarında ham durum kodlarını ya da hata kodlarını elle incelemenize gerek kalmaz.
 
-### Üstel Geri Çekilme (Exponential Backoff)
+### Exception Hiyerarşisi
 
-Yerleşik `ExponentialBackoffPolicy`, denemeler arasında giderek daha uzun süreler (ör. 200ms, 400ms, 800ms) bekler ve "gürleyen sürü" (thundering herd) sorunlarını önlemek için gecikmelere rastgele bir sapma (jitter) ekler.
+```
+BaseAdapterException
+├── HttpException                    (herhangi bir HTTP response hatası)
+│   ├── BadRequestException          (400)
+│   ├── UnauthorizedException        (401)
+│   ├── ForbiddenException           (403)
+│   ├── NotFoundException            (404)
+│   ├── ConflictException            (409)
+│   ├── UnprocessableEntityException (422)
+│   ├── TooManyRequestsException     (429)  ← isRetryable() = true
+│   ├── InternalServerErrorException (500)
+│   ├── BadGatewayException          (502)  ← isRetryable() = true
+│   ├── ServiceUnavailableException  (503)  ← isRetryable() = true
+│   ├── GatewayTimeoutException      (504)  ← isRetryable() = true
+│   └── ... (tüm 4xx / 5xx kodları)
+├── NetworkException                 (OS düzeyindeki bağlantı hataları)
+│   ├── ConnectionRefusedException   (ECONNREFUSED)  ← isRetryable() = true
+│   ├── TimeoutException             (ETIMEDOUT / ECONNABORTED / AbortError)  ← isRetryable() = true
+│   ├── SocketResetException         (ECONNRESET)  ← isRetryable() = true
+│   ├── DnsResolutionException       (ENOTFOUND / EAI_AGAIN)
+│   └── HostUnreachableException     (EHOSTUNREACH / ENETUNREACH)
+├── UnknownException                 (sınıflandırılamayan her türlü hata)
+└── CircuitBreakerOpenException      (circuit açık, request gönderilmedi)
+```
+
+### Exception Türüne Göre Yakalama
+
+```typescript
+import {
+  NotFoundException,
+  TooManyRequestsException,
+  TimeoutException,
+  ConnectionRefusedException,
+  CircuitBreakerOpenException,
+  UnknownException,
+} from '@yildizpay/http-adapter';
+
+try {
+  const response = await adapter.send<PaymentResponse>(request);
+} catch (error) {
+  if (error instanceof NotFoundException) {
+    // HTTP 404 — kaynak bulunamadı
+    console.error('Kaynak bulunamadı:', error.response.data);
+  } else if (error instanceof TooManyRequestsException) {
+    // HTTP 429 — retry'dan önce bekle
+    const retryAfterMs = error.getRetryAfterMs();
+    console.warn(`Rate limit aşıldı. ${retryAfterMs}ms sonra tekrar dene`);
+  } else if (error instanceof TimeoutException) {
+    // ETIMEDOUT / AbortError — downstream servis yavaş
+    console.error('Request timeout:', error.code);
+  } else if (error instanceof ConnectionRefusedException) {
+    // ECONNREFUSED — downstream servis kapalı
+    console.error('Servis kapalı:', error.requestContext?.url);
+  } else if (error instanceof CircuitBreakerOpenException) {
+    // Circuit açık — sunucuya istek gönderilmeden fail fast
+    console.error('Circuit breaker açık. Request gönderilmedi.');
+  } else if (error instanceof UnknownException) {
+    // Beklenmedik bir hata — logla ve araştır
+    console.error('Bilinmeyen hata:', error.toJSON());
+  }
+}
+```
+
+### Type Guard'lar
+
+`instanceof` kullanmadan type narrowing tercih ediyorsanız — fonksiyonel pipeline'larda veya modül sınırlarını geçerken kullanışlıdır — her exception sınıfının karşılık gelen bir type guard'ı mevcuttur:
+
+```typescript
+import {
+  isHttpException,
+  isTimeoutException,
+  isConnectionRefusedException,
+  isCircuitBreakerOpenException,
+} from '@yildizpay/http-adapter';
+
+function handleError(error: unknown): void {
+  if (isTimeoutException(error)) {
+    // TypeScript artık biliyor: error, TimeoutException türünde
+    scheduleRetry(error.requestContext?.url);
+  } else if (isHttpException(error)) {
+    // TypeScript artık biliyor: error, HttpException türünde
+    reportToMonitoring(error.response.status, error.response.data);
+  }
+}
+```
+
+### `isRetryable()` Sinyali
+
+Her exception, hatanın geçici olup olmadığını ve retry'a değer olup olmadığını belirten bir `isRetryable(): boolean` metodu sunar. Custom retry decorator'lar yazarken ya da uygulama katmanında hatayı tekrar denemek isteyip istemediğinize karar verirken kullanışlıdır.
+
+```typescript
+} catch (error) {
+  if (error instanceof BaseAdapterException && error.isRetryable()) {
+    return retryOperation();
+  }
+  throw error;
+}
+```
+
+Retry edilebilir exception'lar: `TooManyRequestsException (429)`, `BadGatewayException (502)`, `ServiceUnavailableException (503)`, `GatewayTimeoutException (504)`, `TimeoutException`, `SocketResetException`, `ConnectionRefusedException`.
+
+### `toJSON()` ile Structured Logging
+
+Tüm exception'lar `toJSON()` metodunu override eder; bu sayede Pino, Winston gibi structured logger'larla tam uyumludur. `JSON.stringify(error)` çağrısı boş `{}` yerine eksiksiz bir log objesi üretir.
+
+```typescript
+} catch (error) {
+  if (error instanceof BaseAdapterException) {
+    logger.error(error.toJSON());
+    // {
+    //   name: 'NotFoundException',
+    //   message: 'Not Found',
+    //   code: 'ERR_NOT_FOUND',
+    //   stack: '...',
+    //   response: {
+    //     status: 404,
+    //     data: { detail: 'Ödeme kaydı bulunamadı' },
+    //     request: { method: 'GET', url: 'https://api.example.com/payments/123', correlationId: 'corr-abc' }
+    //   }
+    // }
+  }
+}
+```
+
+### `RequestContext` — Güvenli Request Metadata
+
+Her exception, kaynak request'ten alınan `RequestContext` objesini (`method`, `url`, `correlationId`) otomatik olarak taşır. Auth token'larının veya kişisel verilerin (PII) loglara sızmasını önlemek amacıyla header ve body bilgileri bu objeden kasıtlı olarak çıkarılmıştır.
+
+```typescript
+} catch (error) {
+  if (error instanceof NetworkException) {
+    logger.warn({
+      event: 'network_failure',
+      exception: error.name,
+      request: error.requestContext, // { method, url, correlationId }
+    });
+  }
+}
+```
+
+### Error Interceptor
+
+Exception'lar business logic'e ulaşmadan önce interceptor seviyesinde yakalanabilir ve dönüştürülebilir.
+
+```typescript
+import {
+  HttpErrorInterceptor,
+  Request,
+  BaseAdapterException,
+  UnauthorizedException,
+} from '@yildizpay/http-adapter';
+
+export class GlobalErrorInterceptor implements HttpErrorInterceptor {
+  async onError(error: BaseAdapterException, request: Request): Promise<never> {
+    if (error instanceof UnauthorizedException) {
+      await this.tokenService.refresh();
+    }
+    // Caller'ın handle edebilmesi için hatayı yeniden fırlat
+    throw error;
+  }
+}
+```
+
+## Resilience & Retry
+
+Ağ kararsızlığı kaçınılmazdır. Bu adaptör, sağlam retry stratejileri tanımlamanıza olanak tanır.
+
+### Exponential Backoff
+
+Built-in `ExponentialBackoffPolicy`, denemeler arasında giderek artan süreler (ör. 200ms, 400ms, 800ms) bekler ve "thundering herd" sorununu önlemek için gecikmelere rastgele jitter ekler.
 
 ```typescript
 import { RetryPolicies } from '@yildizpay/http-adapter';
 
-// 429, 500, 502, 503, 504 durum kodlarında ve ağ hatalarında yeniden dener
+// 429, 502, 503, 504 ve ağ hatalarında retry yapar
 const retryPolicy = RetryPolicies.exponential(5);
 ```
 
-### Devre Kesici (Circuit Breaker)
+### Circuit Breaker
 
-Sisteminizi tamamen çökmüş olan bir sunucuyu beklemekten korumak için `CircuitBreaker` (Devre Kesici) yönteminden yararlanabilirsiniz. Konfigürasyonla belirlenmiş miktarda ardışık hata alındığında devre açılır ve yanıt vermeyen sunucuya gereksiz istek göndermeksizin anında `CircuitBreakerOpenException` fırlatarak cevap verir.
+Tamamen çökmüş bir downstream servisi beklemeye karşı sisteminizi korumak için `CircuitBreaker` kullanabilirsiniz. Belirli sayıda ardışık hata alındığında circuit açılır ve yanıt vermeyen servise gereksiz istek göndermeksizin anında `CircuitBreakerOpenException` fırlatır.
 
 ```typescript
 import { CircuitBreaker } from '@yildizpay/http-adapter';
 
 const breaker = new CircuitBreaker({
-  failureThreshold: 5,         // 5 hatadan sonra devreyi aç
-  resetTimeoutMs: 30000,       // 30 saniye sonra 'yarı-açık' (half-open) test isteği dene
-  successThreshold: 1,         // Yarı-açık durumda 1 başarılı istek sonrası devreyi kapat
+  failureThreshold: 5,         // 5 hatadan sonra circuit'i aç
+  resetTimeoutMs: 30000,       // 30 saniye sonra half-open test isteği gönder
+  successThreshold: 1,         // 1 başarılı half-open request sonrası circuit'i kapat
 });
 ```
 
-## Önleyiciler (Interceptors)
+## Interceptors
 
-**Arayüz Ayrımı Prensibi (ISP)** sayesinde gereksiz tüm metodları uygulamak zorunda kalmazsınız. Tam olarak araya girmek istediğiniz yaşam döngüsüne göre `HttpRequestInterceptor`, `HttpResponseInterceptor` veya `HttpErrorInterceptor` arayüzlerini uygulayabilirsiniz.
+**Interface Segregation Principle (ISP)** sayesinde gereksiz metodları implement etmek zorunda kalmazsınız. Yalnızca ihtiyaç duyduğunuz lifecycle event'e göre `HttpRequestInterceptor`, `HttpResponseInterceptor` veya `HttpErrorInterceptor` interface'ini implement edebilirsiniz.
 
-### 1. İstek Önleyici (Örn: Kimlik Doğrulama)
-İstekler yola çıkmadan önce `Authorization` (Yetkilendirme) gibi başlıkları otomatik ekleyebilirsiniz.
+### 1. Request Interceptor (Örn: Auth Token)
+
+Request'ler gönderilmeden önce `Authorization` gibi header'ları otomatik ekleyebilirsiniz.
 
 ```typescript
 import { HttpRequestInterceptor, Request } from '@yildizpay/http-adapter';
@@ -131,8 +302,9 @@ export class AuthInterceptor implements HttpRequestInterceptor {
 }
 ```
 
-### 2. Yanıt Önleyici (Örn: Veri İzleme ve Dönüşüm)
-Projeye giren tüm başarılı verileri merkezi olarak şekillendirebilir veya loglayabilirsiniz.
+### 2. Response Interceptor (Örn: Veri Dönüşümü)
+
+Gelen tüm response'ları merkezi olarak şekillendirebilir veya loglayabilirsiniz.
 
 ```typescript
 import { HttpResponseInterceptor, Response } from '@yildizpay/http-adapter';
@@ -140,25 +312,30 @@ import { HttpResponseInterceptor, Response } from '@yildizpay/http-adapter';
 export class TransformResponseInterceptor implements HttpResponseInterceptor {
   async onResponse(response: Response): Promise<Response> {
     if (response.status === 201) {
-       console.log('Kaynak başarıyla oluşturuldu!');
+      console.log('Kaynak başarıyla oluşturuldu!');
     }
     return response;
   }
 }
 ```
 
-### 3. Hata Önleyici (Örn: Evrensel Hata Yönetimi)
-Sunucudan gelen hatalı HTTP kodlarını (4xx, 5xx) veya ağ kopmalarını tek bir yerden yakalayıp yönetebilirsiniz.
+### 3. Error Interceptor (Örn: Global Hata Yönetimi)
+
+Sunucudan gelen hatalı HTTP kodlarını (4xx, 5xx) veya ağ hatalarını tek bir yerden yakalayıp yönetebilirsiniz.
 
 ```typescript
-import { HttpErrorInterceptor, Request, HttpClientException } from '@yildizpay/http-adapter';
+import {
+  HttpErrorInterceptor,
+  Request,
+  BaseAdapterException,
+  UnauthorizedException,
+} from '@yildizpay/http-adapter';
 
 export class GlobalErrorInterceptor implements HttpErrorInterceptor {
-  async onError(error: unknown, request: Request): Promise<unknown> {
-    if (error instanceof HttpClientException && error.response?.status === 401) {
-       console.error(`${request.endpoint} uç noktasına yetkisiz erişim! Login sayfasına yönlendiriliyor...`);
+  async onError(error: BaseAdapterException, request: Request): Promise<never> {
+    if (error instanceof UnauthorizedException) {
+      console.error(`${error.requestContext?.url} endpoint'ine yetkisiz erişim!`);
     }
-    // Hatayı fırlatmaya devam edebilir veya varsayılan bir veri (fallback) dönebilirsiniz
     throw error;
   }
 }
@@ -166,7 +343,7 @@ export class GlobalErrorInterceptor implements HttpErrorInterceptor {
 
 ## Katkıda Bulunma
 
-Katkılarınızı her zaman bekliyoruz! Lütfen bir "Pull Request" göndermekten çekinmeyin.
+Katkılarınızı her zaman bekliyoruz! Lütfen bir Pull Request göndermekten çekinmeyin.
 
 ## Lisans
 

package/dist/contracts/http-client.contract.d.ts

@@ -15,12 +15,3 @@ export interface HttpClientResponse<T = unknown> {
 export interface HttpClientContract {
     request<T = unknown>(config: HttpClientRequestConfig): Promise<HttpClientResponse<T>>;
 }
-export declare class HttpClientException<T = unknown> extends Error {
-    readonly response?: {
-        status: number;
-        data: T;
-        headers: Record<string, string>;
-    };
-    readonly code?: string;
-    constructor(message: string, status?: number, data?: T, headers?: Record<string, string>, code?: string);
-}

package/dist/contracts/http-client.contract.js

@@ -1,20 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpClientException = void 0;
-class HttpClientException extends Error {
-    constructor(message, status, data, headers, code) {
-        super(message);
-        this.name = 'HttpClientException';
-        Object.setPrototypeOf(this, HttpClientException.prototype);
-        if (status !== undefined) {
-            this.response = {
-                status,
-                data: data,
-                headers: headers ?? {},
-            };
-        }
-        this.code = code;
-    }
-}
-exports.HttpClientException = HttpClientException;
 //# sourceMappingURL=http-client.contract.js.map

package/dist/contracts/http-client.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-client.contract.js","sourceRoot":"","sources":["../../src/contracts/http-client.contract.ts"],"names":[],"mappings":";;;AAkCA,MAAa,mBAAiC,SAAQ,KAAK;IAQzD,YACE,OAAe,EACf,MAAe,EACf,IAAQ,EACR,OAAgC,EAChC,IAAa;QAEb,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;QAE3D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,QAAQ,GAAG;gBACd,MAAM;gBACN,IAAI,EAAE,IAAS;gBACf,OAAO,EAAE,OAAO,IAAI,EAAE;aACvB,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AA5BD,kDA4BC"}
+{"version":3,"file":"http-client.contract.js","sourceRoot":"","sources":["../../src/contracts/http-client.contract.ts"],"names":[],"mappings":""}