# API Integration Guide - Retail POS App

## Overview

This guide provides comprehensive documentation for the API integration layer of the Retail POS application. The integration is built using **Dio** for HTTP requests with a robust error handling, retry logic, and offline-first architecture.

---

## Architecture

### Layered Architecture

```
Presentation Layer (UI)
        “
   Providers (Riverpod)
        “
    Use Cases
        “
   Repositories
        “
   Data Sources (Remote + Local)
        “
  Network Layer (Dio)
```

---

## Components

### 1. DioClient (`/lib/core/network/dio_client.dart`)

**Purpose**: Centralized HTTP client configuration with Dio.

**Features**:
- Base URL and timeout configuration
- Request/response interceptors
- Authentication header management
- Automatic retry logic
- Error handling and conversion to custom exceptions

**Usage Example**:
```dart
final dioClient = DioClient();

// GET request
final response = await dioClient.get('/products');

// POST request
final response = await dioClient.post(
  '/products',
  data: {'name': 'Product Name', 'price': 29.99},
);

// With query parameters
final response = await dioClient.get(
  '/products/search',
  queryParameters: {'q': 'laptop'},
);
```

**Methods**:
- `get()` - GET requests
- `post()` - POST requests
- `put()` - PUT requests
- `delete()` - DELETE requests
- `patch()` - PATCH requests
- `download()` - File downloads
- `updateAuthToken()` - Update authentication token
- `removeAuthToken()` - Remove authentication token
- `addHeader()` - Add custom header
- `removeHeader()` - Remove custom header

---

### 2. API Constants (`/lib/core/constants/api_constants.dart`)

**Purpose**: Centralized configuration for API endpoints, timeouts, and settings.

**Configuration**:
```dart
// Base URL
static const String baseUrl = 'https://api.retailpos.example.com';
static const String apiVersion = '/api/v1';

// Timeouts (in milliseconds)
static const int connectTimeout = 30000;
static const int receiveTimeout = 30000;
static const int sendTimeout = 30000;

// Retry configuration
static const int maxRetries = 3;
static const int retryDelay = 1000;
```

**Endpoints**:
```dart
// Products
ApiConstants.products              // GET /products
ApiConstants.productById('123')    // GET /products/123
ApiConstants.productsByCategory('cat1') // GET /products/category/cat1
ApiConstants.searchProducts        // GET /products/search?q=query
ApiConstants.syncProducts          // POST /products/sync

// Categories
ApiConstants.categories            // GET /categories
ApiConstants.categoryById('123')   // GET /categories/123
ApiConstants.syncCategories        // POST /categories/sync
```

---

### 3. Network Info (`/lib/core/network/network_info.dart`)

**Purpose**: Check network connectivity status using `connectivity_plus`.

**Features**:
- Check current connectivity status
- Stream of connectivity changes
- Check connection type (WiFi, Mobile, etc.)

**Usage Example**:
```dart
final networkInfo = NetworkInfoImpl(Connectivity());

// Check if connected
final isConnected = await networkInfo.isConnected;

// Listen to connectivity changes
networkInfo.onConnectivityChanged.listen((isConnected) {
  if (isConnected) {
    print('Device is online');
  } else {
    print('Device is offline');
  }
});

// Check connection type
final isWiFi = await networkInfo.isConnectedViaWiFi;
final isMobile = await networkInfo.isConnectedViaMobile;
```

---

### 4. API Interceptors (`/lib/core/network/api_interceptor.dart`)

#### Logging Interceptor
Logs all requests and responses for debugging.

```dart
REQUEST[GET] => PATH: /products
Headers: {Content-Type: application/json}
RESPONSE[200] => PATH: /products
Data: {...}
```

#### Authentication Interceptor
Automatically adds authentication headers to requests.

```dart
// Set auth token
authInterceptor.setAuthToken('your-jwt-token');

// All requests now include:
// Authorization: Bearer your-jwt-token

// Clear token
authInterceptor.clearAuthToken();
```

#### Error Interceptor
Converts HTTP status codes to custom exceptions.

**Status Code Mapping**:
- `400` ’ `BadRequestException`
- `401` ’ `UnauthorizedException`
- `403` ’ `ForbiddenException`
- `404` ’ `NotFoundException`
- `422` ’ `ValidationException`
- `429` ’ `RateLimitException`
- `500+` ’ `ServerException`
- `503` ’ `ServiceUnavailableException`

#### Retry Interceptor
Automatically retries failed requests.

**Retry Conditions**:
- Connection timeout
- Send/receive timeout
- Connection errors
- HTTP 408, 429, 502, 503, 504

**Retry Strategy**:
- Max retries: 3 (configurable)
- Exponential backoff: delay * (retry_count + 1)
- Default delay: 1000ms

---

### 5. Custom Exceptions (`/lib/core/errors/exceptions.dart`)

**Network Exceptions**:
- `NoInternetException` - No internet connection
- `TimeoutException` - Request timeout
- `ConnectionException` - Connection failed
- `NetworkException` - General network error

**Server Exceptions**:
- `ServerException` - Server error (500+)
- `ServiceUnavailableException` - Service unavailable (503)

**Client Exceptions**:
- `BadRequestException` - Invalid request (400)
- `UnauthorizedException` - Authentication required (401)
- `ForbiddenException` - Access forbidden (403)
- `NotFoundException` - Resource not found (404)
- `ValidationException` - Validation failed (422)
- `RateLimitException` - Rate limit exceeded (429)

**Cache Exceptions**:
- `CacheException` - Cache operation failed
- `CacheNotFoundException` - Data not found in cache

**Data Exceptions**:
- `DataParsingException` - Failed to parse data
- `InvalidDataFormatException` - Invalid data format

**Business Exceptions**:
- `OutOfStockException` - Product out of stock
- `InsufficientStockException` - Insufficient stock
- `TransactionException` - Transaction failed
- `PaymentException` - Payment processing failed

---

### 6. Failure Classes (`/lib/core/errors/failures.dart`)

Failures are used in the domain/presentation layer to represent errors without throwing exceptions.

**Network Failures**:
- `NoInternetFailure`
- `ConnectionFailure`
- `TimeoutFailure`
- `NetworkFailure`

**Server Failures**:
- `ServerFailure`
- `ServiceUnavailableFailure`

**Client Failures**:
- `BadRequestFailure`
- `UnauthorizedFailure`
- `ForbiddenFailure`
- `NotFoundFailure`
- `ValidationFailure`
- `RateLimitFailure`

**Usage Pattern**:
```dart
// In repository
try {
  final products = await remoteDataSource.fetchProducts();
  return Right(products);
} on NoInternetException {
  return Left(NoInternetFailure());
} on ServerException catch (e) {
  return Left(ServerFailure(e.message, e.statusCode));
} catch (e) {
  return Left(NetworkFailure('Unexpected error: ${e.toString()}'));
}
```

---

### 7. Remote Data Sources

#### Product Remote Data Source (`/lib/features/products/data/datasources/product_remote_datasource.dart`)

**Methods**:
```dart
// Fetch all products
Future<List<ProductModel>> fetchProducts();

// Fetch single product
Future<ProductModel> fetchProductById(String id);

// Fetch products by category
Future<List<ProductModel>> fetchProductsByCategory(String categoryId);

// Search products
Future<List<ProductModel>> searchProducts(String query);

// Sync products
Future<void> syncProducts(List<ProductModel> products);
```

**Usage Example**:
```dart
final dataSource = ProductRemoteDataSourceImpl(dioClient);

// Fetch all products
final products = await dataSource.fetchProducts();

// Search products
final results = await dataSource.searchProducts('laptop');

// Fetch by category
final categoryProducts = await dataSource.fetchProductsByCategory('electronics');
```

#### Category Remote Data Source (`/lib/features/categories/data/datasources/category_remote_datasource.dart`)

**Methods**:
```dart
// Fetch all categories
Future<List<CategoryModel>> fetchCategories();

// Fetch single category
Future<CategoryModel> fetchCategoryById(String id);

// Sync categories
Future<void> syncCategories(List<CategoryModel> categories);
```

---

## Setup & Installation

### 1. Dependencies

Already added to `pubspec.yaml`:
```yaml
dependencies:
  dio: ^5.7.0
  connectivity_plus: ^6.1.1
  equatable: ^2.0.7
  get_it: ^8.0.4
```

### 2. Initialize Dependencies

In `main.dart`:
```dart
import 'package:flutter/material.dart';
import 'core/di/injection_container.dart' as di;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize dependencies
  await di.initDependencies();

  runApp(const MyApp());
}
```

### 3. Configure API Base URL

Update in `/lib/core/constants/api_constants.dart`:
```dart
static const String baseUrl = 'https://your-api-url.com';
```

### 4. Using Mock Data (Development)

Enable mock data in `/lib/core/constants/api_constants.dart`:
```dart
static const bool useMockData = true;
```

---

## Usage Examples

### Example 1: Fetch Products in a Repository

```dart
import 'package:dartz/dartz.dart';
import '../../../core/errors/exceptions.dart';
import '../../../core/errors/failures.dart';
import '../../domain/repositories/product_repository.dart';
import '../datasources/product_remote_datasource.dart';
import '../models/product_model.dart';

class ProductRepositoryImpl implements ProductRepository {
  final ProductRemoteDataSource remoteDataSource;
  final NetworkInfo networkInfo;

  ProductRepositoryImpl({
    required this.remoteDataSource,
    required this.networkInfo,
  });

  @override
  Future<Either<Failure, List<ProductModel>>> getProducts() async {
    // Check network connectivity
    if (!await networkInfo.isConnected) {
      return Left(NoInternetFailure());
    }

    try {
      final products = await remoteDataSource.fetchProducts();
      return Right(products);
    } on ServerException catch (e) {
      return Left(ServerFailure(e.message, e.statusCode));
    } on TimeoutException {
      return Left(TimeoutFailure());
    } on NetworkException catch (e) {
      return Left(NetworkFailure(e.message, e.statusCode));
    } catch (e) {
      return Left(NetworkFailure('Unexpected error: ${e.toString()}'));
    }
  }
}
```

### Example 2: Using in a Riverpod Provider

```dart
import 'package:riverpod_annotation/riverpod_annotation.dart';
import '../../../core/di/injection_container.dart';
import '../../data/datasources/product_remote_datasource.dart';
import '../../data/models/product_model.dart';

part 'products_provider.g.dart';

@riverpod
class Products extends _$Products {
  @override
  Future<List<ProductModel>> build() async {
    final dataSource = sl<ProductRemoteDataSource>();
    return await dataSource.fetchProducts();
  }

  Future<void> refresh() async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(() async {
      final dataSource = sl<ProductRemoteDataSource>();
      return await dataSource.fetchProducts();
    });
  }
}
```

### Example 3: Handling Errors in UI

```dart
// In your widget
Consumer(
  builder: (context, ref, child) {
    final productsAsync = ref.watch(productsProvider);

    return productsAsync.when(
      data: (products) => ProductGrid(products: products),
      loading: () => const CircularProgressIndicator(),
      error: (error, stack) {
        // Handle different error types
        if (error is NoInternetFailure) {
          return ErrorWidget(
            message: 'No internet connection',
            onRetry: () => ref.refresh(productsProvider),
          );
        } else if (error is ServerFailure) {
          return ErrorWidget(
            message: 'Server error. Please try again later',
            onRetry: () => ref.refresh(productsProvider),
          );
        }
        return ErrorWidget(
          message: 'An error occurred',
          onRetry: () => ref.refresh(productsProvider),
        );
      },
    );
  },
);
```

---

## Testing

### Testing Network Connectivity

```dart
// Use mock implementation
final mockNetworkInfo = NetworkInfoMock(isConnected: false);

// Test offline scenario
final repository = ProductRepositoryImpl(
  remoteDataSource: mockRemoteDataSource,
  networkInfo: mockNetworkInfo,
);

final result = await repository.getProducts();
expect(result.isLeft(), true);
expect(result.fold((l) => l, (r) => null), isA<NoInternetFailure>());
```

### Testing API Calls

```dart
// Use mock data source
final mockDataSource = ProductRemoteDataSourceMock();

final products = await mockDataSource.fetchProducts();
expect(products, isNotEmpty);
expect(products.first.name, 'Sample Product 1');
```

---

## API Response Format

### Expected JSON Response Formats

#### Products List
```json
{
  "products": [
    {
      "id": "1",
      "name": "Product Name",
      "description": "Product description",
      "price": 29.99,
      "imageUrl": "https://example.com/image.jpg",
      "categoryId": "cat1",
      "stockQuantity": 100,
      "isAvailable": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

Or direct array:
```json
[
  {
    "id": "1",
    "name": "Product Name",
    ...
  }
]
```

#### Single Product
```json
{
  "product": {
    "id": "1",
    "name": "Product Name",
    ...
  }
}
```

#### Categories List
```json
{
  "categories": [
    {
      "id": "1",
      "name": "Electronics",
      "description": "Electronic devices",
      "iconPath": "assets/icons/electronics.png",
      "color": "#2196F3",
      "productCount": 25,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

#### Error Response
```json
{
  "message": "Error message",
  "error": "Detailed error",
  "errors": {
    "field1": ["Validation error 1"],
    "field2": ["Validation error 2"]
  }
}
```

---

## Troubleshooting

### Issue: Connection Timeout

**Solution**:
- Increase timeout in `api_constants.dart`
- Check network connectivity
- Verify API endpoint is accessible

### Issue: SSL Certificate Error

**Solution**:
In development, you can allow self-signed certificates:
```dart
(_dio.httpClientAdapter as IOHttpClientAdapter).createHttpClient = () {
  final client = HttpClient();
  client.badCertificateCallback = (cert, host, port) => true;
  return client;
};
```

**  Warning**: Never use this in production!

### Issue: 401 Unauthorized

**Solution**:
- Check authentication token is set correctly
- Verify token hasn't expired
- Refresh token if necessary

### Issue: Data Parsing Error

**Solution**:
- Verify API response format matches expected format
- Check JSON field names match model properties
- Add debug logging to see actual response

---

## Best Practices

1. **Always check network connectivity** before making API calls
2. **Use offline-first approach** - read from cache first, sync in background
3. **Handle all error scenarios** gracefully with user-friendly messages
4. **Implement proper retry logic** for transient errors
5. **Log requests/responses** in development, disable in production
6. **Use mock data sources** for development and testing
7. **Implement request cancellation** for expensive operations
8. **Cache API responses** to improve performance
9. **Use proper timeout values** based on expected response time
10. **Implement proper authentication** token management

---

## Next Steps

1. **Implement Repositories**: Create repository implementations
2. **Add Use Cases**: Define business logic in use cases
3. **Create Riverpod Providers**: Wire up data layer with UI
4. **Implement Offline Sync**: Add background sync logic
5. **Add Authentication**: Implement OAuth/JWT authentication
6. **Implement Caching**: Add response caching with Hive
7. **Add Pagination**: Implement paginated API requests
8. **Error Tracking**: Integrate error tracking (Sentry, Firebase Crashlytics)

---

## Support & Resources

- **Dio Documentation**: https://pub.dev/packages/dio
- **Connectivity Plus**: https://pub.dev/packages/connectivity_plus
- **GetIt Documentation**: https://pub.dev/packages/get_it
- **Riverpod Documentation**: https://riverpod.dev

---

## File Structure

```
lib/
 core/
    constants/
       api_constants.dart            API configuration
    di/
       injection_container.dart      Dependency injection
    errors/
       exceptions.dart               Custom exceptions
       failures.dart                 Failure classes
    network/
        dio_client.dart               Dio HTTP client
        api_interceptor.dart          Interceptors
        network_info.dart             Network connectivity
 features/
    products/
       data/
           datasources/
              product_remote_datasource.dart  
           models/
               product_model.dart   
    categories/
        data/
            datasources/
               category_remote_datasource.dart 
            models/
                category_model.dart  
```

---

**All API integration components are now complete and ready to use!** <‰