@yildizpay/http-adapter 3.0.0 → 3.2.0

package/README.md

@@ -11,6 +11,8 @@ 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.
+- **Response Validation:** Attach one or more `ResponseValidator` implementations to any request to enforce schema constraints or business rules automatically before the response reaches your code.
 - **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 +55,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 +64,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 +86,241 @@ 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 }
+    });
+  }
+}
+```
+
+### Response Validators
+
+Attach validators to a request to automatically enforce schema constraints or business rules on the response before it reaches your code. Validators run sequentially after the HTTP call succeeds and before response-side interceptors. The first validator that throws halts the chain.
+
+```typescript
+import { ResponseValidator, ValidationException, Response } from '@yildizpay/http-adapter';
+
+class PaymentStatusValidator implements ResponseValidator<IyzicoResponse> {
+  validate(response: Response<IyzicoResponse>): void {
+    if (response.data.status !== 'success') {
+      throw new ValidationException(
+        `Payment failed: ${response.data.errorMessage}`,
+        response,
+      );
+    }
+  }
+}
+
+// Works with any schema validation library — zero coupling to Zod, Joi, etc.
+class PaymentSchemaValidator implements ResponseValidator<unknown> {
+  validate(response: Response<unknown>): void {
+    IyzicoResponseSchema.parse(response.data); // Zod throws on mismatch
+  }
+}
+
+const request = new RequestBuilder('https://api.iyzipay.com')
+  .setEndpoint('/payment/auth')
+  .setMethod(HttpMethod.POST)
+  .setBody(dto)
+  .validateWith(new PaymentSchemaValidator(), new PaymentStatusValidator())
+  .build();
+```
+
+Catching a validation failure:
+
+```typescript
+import { isValidationException } from '@yildizpay/http-adapter';
+
+} catch (error) {
+  if (isValidationException(error)) {
+    console.error('Validation failed:', error.message);
+    console.error('Raw response:', error.response.data);
+  }
+}
+```
+
+Non-`BaseAdapterException` errors thrown inside a validator (e.g. `ZodError`) are automatically wrapped in `ValidationException` with the original error available as `cause`. Use the generic parameter for typed access:
+
+```typescript
+} catch (error) {
+  if (isValidationException<ZodError>(error) && error.cause) {
+    console.error('Schema issues:', error.cause.issues);
+  }
+}
+```
+
+The full interceptor lifecycle when validators are registered:
+
+```
+onRequest → HTTP call → onResponse → validators → onResponseValidated → caller
+                                          ↓ (on failure)
+                                       onError
+```
+
+`onResponse` always fires. `onResponseValidated` only fires when all validators pass — ideal for caching or downstream side effects that require a business-valid response.
+
+### 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 +332,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 +355,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 +370,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 +379,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 +387,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;
   }
 }