http-request-manager 18.15.32 → 18.15.34

package/src/docs/INTERCEPTOR_README.md

@@ -0,0 +1,549 @@
+# HTTP Interceptors
+
+The HTTP Request Manager library provides a comprehensive set of HTTP interceptors that are automatically configured to enhance and secure your HTTP requests.
+
+## Overview
+
+Interceptors are a powerful feature in Angular that allow you to intercept and modify HTTP requests and responses globally. This library provides several interceptors that handle common HTTP concerns such as error handling, authentication, and headers management.
+
+## Available Interceptors
+
+### 1. RequestErrorInterceptor
+
+Handles HTTP error responses (400/500 status codes) with automatic toast notifications.
+
+**Features:**
+- **Client Error Handling** - Displays warnings for 4xx errors
+- **Server Error Handling** - Displays errors for 5xx errors
+- **Toast Notifications** - Shows user-friendly error messages using `ToastMessageDisplayService`
+- **Detailed Logging** - Logs comprehensive error information to console
+
+**Behavior:**
+- **400-499 Errors**: Shows a warning toast with error details
+- **500+ Errors**: Shows an error toast with error details
+- **Error Details**: Logs status, message, error object, and status text
+
+**Installation:**
+
+```typescript
+import { RequestErrorInterceptor } from 'http-request-manager';
+
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestErrorInterceptor, 
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+**Customization:**
+
+The interceptor uses `ToastMessageDisplayService` to display errors. Ensure you have the `toast-message-display` library installed:
+
+```typescript
+import { ToastMessageDisplayService } from 'toast-message-display';
+```
+
+### 2. RequestHeadersInterceptor
+
+Automatically adds common headers to all HTTP requests.
+
+**Features:**
+- **Content-Type** - Sets `application/json` for all requests
+- **Accept-Language** - Adds language header based on current locale
+- **Current-Date** - Adds current date in YYYY-MM-DD format
+- **Dynamic Language** - Automatically updates when language changes via `@ngx-translate/core`
+
+**Default Headers:**
+- `Content-Type: application/json`
+- `Accept-Language: {current-locale}-CA` (e.g., `en-CA`, `fr-CA`)
+- `Current-Date: {YYYY-MM-DD}`
+
+**Installation:**
+
+```typescript
+import { RequestHeadersInterceptor } from 'http-request-manager';
+
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestHeadersInterceptor, 
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+**Dependencies:**
+
+This interceptor requires `@ngx-translate/core` for language management:
+
+```typescript
+import { TranslateService } from '@ngx-translate/core';
+```
+
+**Language Format:**
+
+The interceptor automatically formats the language as `{language}-CA`. For example:
+- `en` → `en-CA`
+- `fr` → `fr-CA`
+- `es` → `es-CA`
+
+### 3. CredentialsInterceptor
+
+Adds `withCredentials: true` to all HTTP requests to include cookies and authentication headers in cross-origin requests.
+
+**Features:**
+- **Cookie Support** - Includes cookies in cross-origin requests
+- **Authentication Headers** - Sends authentication headers automatically
+- **CORS Configuration** - Works with CORS-enabled backends
+
+**Installation:**
+
+```typescript
+import { CredentialsInterceptor } from 'http-request-manager';
+
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: CredentialsInterceptor, 
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+**Use Case:**
+
+Use this interceptor when your backend requires:
+- Cookie-based authentication
+- CORS with credentials
+- Session management
+
+### 4. ProxyDebuggerInterceptor
+
+Provides debugging capabilities for HTTP requests during development.
+
+**Features:**
+- **Request Logging** - Logs all HTTP requests to console
+- **Response Logging** - Logs HTTP responses to console
+- **Timing Information** - Logs request/response timing
+- **Debug Mode** - Can be enabled/disabled based on environment
+
+**Installation:**
+
+```typescript
+import { ProxyDebuggerInterceptor } from 'http-request-manager';
+
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: ProxyDebuggerInterceptor, 
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+**Note:**
+
+This interceptor is primarily used during development. Consider disabling it in production builds.
+
+## Auto-Configuration
+
+All interceptors are automatically configured when you import `HttpRequestManagerModule`:
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({})]
+})
+export class AppModule { }
+```
+
+With this configuration, all four interceptors are automatically applied to your HTTP requests.
+
+## Manual Configuration
+
+If you want to manually configure interceptors, you can do so in your module providers:
+
+```typescript
+import { 
+  HTTP_INTERCEPTORS,
+  HttpClientModule,
+  RequestErrorInterceptor,
+  RequestHeadersInterceptor,
+  CredentialsInterceptor,
+  ProxyDebuggerInterceptor
+} from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpClientModule],
+  providers: [
+    // Order matters! Interceptors are applied in the order they are defined
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: ProxyDebuggerInterceptor,  // Applied first (outermost)
+      multi: true 
+    },
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestErrorInterceptor,    // Applied second
+      multi: true 
+    },
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestHeadersInterceptor,  // Applied third
+      multi: true 
+    },
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: CredentialsInterceptor,    // Applied last (innermost)
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+## Interceptor Order
+
+The order of interceptors matters! Interceptors are applied from last to first:
+
+1. **ProxyDebuggerInterceptor** (outermost) - Logs the original request
+2. **RequestErrorInterceptor** - Catches errors from the response
+3. **RequestHeadersInterceptor** - Adds headers to the request
+4. **CredentialsInterceptor** (innermost) - Adds credentials to the request
+
+**Flow:**
+```
+Request → ProxyDebugger → RequestError → Headers → Credentials → HttpClient
+Response ← ProxyDebugger ← RequestError ← Headers ← Credentials ← HttpClient
+```
+
+## Disabling Interceptors
+
+If you want to disable certain interceptors, you can either:
+
+### Option 1: Manual Configuration
+
+Only include the interceptors you need:
+
+```typescript
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestHeadersInterceptor, 
+      multi: true 
+    }
+    // Omit other interceptors
+  ]
+})
+export class AppModule { }
+```
+
+### Option 2: Use Skip Headers
+
+Add a custom header to skip specific interceptors (if interceptors support this):
+
+```typescript
+http.get('/api/data', {
+  headers: { 'Skip-Interceptors': 'RequestErrorInterceptor' }
+});
+```
+
+## Custom Interceptors
+
+You can create your own interceptors and use them alongside the library's interceptors:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HttpRequest, HttpHandler, HttpEvent, HttpInterceptor } from '@angular/common/http';
+import { Observable } from 'rxjs';
+
+@Injectable()
+export class CustomInterceptor implements HttpInterceptor {
+  intercept(
+    request: HttpRequest<any>, 
+    next: HttpHandler
+  ): Observable<HttpEvent<any>> {
+    // Modify the request
+    const modifiedRequest = request.clone({
+      setHeaders: {
+        'X-Custom-Header': 'custom-value'
+      }
+    });
+    
+    return next.handle(modifiedRequest);
+  }
+}
+
+// Register it in your module
+@NgModule({
+  providers: [
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: CustomInterceptor, 
+      multi: true 
+    }
+  ]
+})
+export class AppModule { }
+```
+
+## Error Handling
+
+### RequestErrorInterceptor Behavior
+
+The `RequestErrorInterceptor` handles errors as follows:
+
+#### Client Errors (400-499)
+
+```typescript
+// Toast Display
+{
+  message: error.error || "400: Bad Request",
+  action: "OK",
+  color: ToastColors.WARN,
+  icon: "info",
+  duration: 5000
+}
+
+// Console Log
+{
+  status: 400,
+  message: "Error message",
+  error: { ... },
+  text: "Bad Request"
+}
+```
+
+#### Server Errors (500+)
+
+```typescript
+// Toast Display
+{
+  message: error.error || "500: Internal Server Error",
+  action: "OK",
+  color: ToastColors.ERROR,
+  icon: "info",
+  duration: 5000
+}
+
+// Console Log
+{
+  status: 500,
+  message: "Error message",
+  error: { ... },
+  text: "Internal Server Error"
+}
+```
+
+### Custom Error Handling
+
+To customize error handling, you can:
+
+1. **Disable RequestErrorInterceptor** and create your own
+2. **Add additional interceptors** to handle specific error cases
+3. **Catch errors in your services** using RxJS operators
+
+```typescript
+// Example: Custom error handling in service
+http.get('/api/data').pipe(
+  catchError(error => {
+    if (error.status === 401) {
+      // Handle unauthorized
+      this.router.navigate(['/login']);
+    } else if (error.status === 403) {
+      // Handle forbidden
+      this.notification.show('Access denied');
+    }
+    return throwError(() => error);
+  })
+);
+```
+
+## Best Practices
+
+### 1. Use Appropriate Interceptors
+
+- **Development**: Enable `ProxyDebuggerInterceptor` for debugging
+- **Production**: Disable `ProxyDebuggerInterceptor` to improve performance
+- **Authentication**: Always use `CredentialsInterceptor` for authenticated requests
+- **Error Handling**: Use `RequestErrorInterceptor` for consistent error messages
+
+### 2. Configure Interceptor Order Correctly
+
+Remember that interceptors are applied from last to first:
+
+```typescript
+providers: [
+  // First interceptor (outermost)
+  { provide: HTTP_INTERCEPTORS, useClass: FirstInterceptor, multi: true },
+  // Second interceptor
+  { provide: HTTP_INTERCEPTORS, useClass: SecondInterceptor, multi: true },
+  // Last interceptor (innermost)
+  { provide: HTTP_INTERCEPTORS, useClass: LastInterceptor, multi: true }
+]
+```
+
+### 3. Handle Interceptor Dependencies
+
+Some interceptors have dependencies:
+
+- `RequestHeadersInterceptor` requires `@ngx-translate/core`
+- `RequestErrorInterceptor` requires `toast-message-display`
+
+Ensure these dependencies are installed and configured.
+
+### 4. Test Your Interceptors
+
+Write unit tests for custom interceptors:
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { HTTP_INTERCEPTORS, HttpClient } from '@angular/common/http';
+import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing';
+
+describe('CustomInterceptor', () => {
+  let http: HttpClient;
+  let httpMock: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [HttpClientTestingModule],
+      providers: [
+        { provide: HTTP_INTERCEPTORS, useClass: CustomInterceptor, multi: true }
+      ]
+    });
+    http = TestBed.inject(HttpClient);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  it('should add custom header', () => {
+    http.get('/api/test').subscribe();
+    const req = httpMock.expectOne('/api/test');
+    expect(req.request.headers.get('X-Custom-Header')).toBe('custom-value');
+  });
+});
+```
+
+### 5. Monitor Performance
+
+Interceptors add overhead to HTTP requests. Monitor performance and:
+- Remove unused interceptors
+- Optimize interceptor logic
+- Disable debug interceptors in production
+
+## Environment-Specific Configuration
+
+You can configure interceptors differently based on the environment:
+
+```typescript
+import { environment } from '../environments/environment';
+
+@NgModule({
+  providers: [
+    // Always include these
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestHeadersInterceptor, 
+      multi: true 
+    },
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: CredentialsInterceptor, 
+      multi: true 
+    },
+    { 
+      provide: HTTP_INTERCEPTORS, 
+      useClass: RequestErrorInterceptor, 
+      multi: true 
+    },
+    // Only in development
+    ...(environment.production ? [] : [
+      { 
+        provide: HTTP_INTERCEPTORS, 
+        useClass: ProxyDebuggerInterceptor, 
+        multi: true 
+      }
+    ])
+  ]
+})
+export class AppModule { }
+```
+
+## Troubleshooting
+
+### Interceptors Not Working
+
+**Possible Causes:**
+- Interceptors not registered in providers
+- Wrong module imports
+- Interceptor order issues
+
+**Solutions:**
+- Verify interceptors are registered with `HTTP_INTERCEPTORS` token
+- Ensure `multi: true` is set
+- Check module imports and providers configuration
+
+### Headers Not Being Added
+
+**Possible Causes:**
+- `RequestHeadersInterceptor` not configured
+- Request already has conflicting headers
+- Interceptor order issues
+
+**Solutions:**
+- Verify `RequestHeadersInterceptor` is registered
+- Check if other interceptors are modifying headers
+- Review interceptor order
+
+### Cookies Not Being Sent
+
+**Possible Causes:**
+- `CredentialsInterceptor` not configured
+- CORS not configured on backend
+- SameSite cookie attribute blocking
+
+**Solutions:**
+- Ensure `CredentialsInterceptor` is registered
+- Configure CORS on backend with `credentials: true`
+- Check cookie SameSite attribute
+
+### Errors Not Showing in Toast
+
+**Possible Causes:**
+- `RequestErrorInterceptor` not configured
+- `toast-message-display` not installed
+- Toast service not configured
+
+**Solutions:**
+- Verify `RequestErrorInterceptor` is registered
+- Install `toast-message-display` library
+- Configure toast service in app module
+
+## Related Documentation
+
+- [`HTTPManagerService`](HTTP_MANAGER_README.md) - HTTP request management
+- [`HTTPManagerStateService`](HTTP_STATE_MANAGER_README.md) - State management
+- [`UtilsService`](UTILS_README.md) - Utility functions
+
+## Angular Documentation
+
+For more information about interceptors, see:
+
+- [Angular HTTP Interceptors Guide](https://angular.io/guide/http#intercepting-requests-and-responses)
+- [HttpClient Documentation](https://angular.io/api/common/http/HttpClient)