# Freebit SIM Management - Implementation Guide

*Complete implementation of Freebit SIM management functionality for the Customer Portal.*

## Overview

This document outlines the complete implementation of Freebit SIM management features, including backend API integration, frontend UI components, and Salesforce data tracking requirements.

## 🏗️ Implementation Summary

### ✅ Completed Features

1. **Backend (BFF) Integration**
   - Freebit API service with all endpoints
   - SIM management service layer
   - REST API endpoints for portal consumption
   - Authentication and error handling

2. **Frontend (Portal) Components**
   - SIM details card with status and information
   - Data usage chart with visual progress tracking
   - SIM management actions (top-up, cancel, reissue)
   - Interactive top-up modal with presets and scheduling
   - Integrated into subscription detail page

3. **Features Implemented**
   - View SIM details (ICCID, MSISDN, plan, status)
   - Real-time data usage monitoring
   - Data quota top-up (immediate and scheduled)
   - eSIM profile reissue
   - SIM service cancellation
   - Plan change functionality
   - Usage history tracking

## 🔧 API Endpoints

### Backend (BFF) Endpoints

All endpoints are prefixed with `/api/subscriptions/{id}/sim/`

- `GET /` - Get comprehensive SIM info (details + usage)
- `GET /details` - Get SIM details only
- `GET /usage` - Get data usage information
- `GET /top-up-history?fromDate=&toDate=` - Get top-up history
- `POST /top-up` - Add data quota
- `POST /change-plan` - Change SIM plan
- `POST /cancel` - Cancel SIM service
- `POST /reissue-esim` - Reissue eSIM profile (eSIM only)

### Freebit API Integration

**Implemented Freebit APIs:**
- PA01-01: OEM Authentication (`/authOem/`)
- PA03-02: Get Account Details (`/mvno/getDetail/`)
- PA04-04: Add Specs & Quota (`/master/addSpec/`)
- PA05-0: MVNO Communication Information Retrieval (`/mvno/getTrafficInfo/`)
- PA05-02: MVNO Quota Addition History (`/mvno/getQuotaHistory/`)
- PA05-04: MVNO Plan Cancellation (`/mvno/releasePlan/`)
- PA05-21: MVNO Plan Change (`/mvno/changePlan/`)
- PA05-22: MVNO Quota Settings (`/mvno/eachQuota/`)
- PA05-42: eSIM Profile Reissue (`/esim/reissueProfile/`)
- **Enhanced**: eSIM Add Account/Reissue (`/mvno/esim/addAcnt/`) - Based on Salesforce implementation

**Note**: The implementation includes both the simple reissue endpoint and the enhanced addAcnt method for more complex eSIM reissue scenarios, matching your existing Salesforce integration patterns.

## 🎨 Frontend Components

### Component Structure
```
apps/portal/src/features/sim-management/
├── components/
│   ├── SimManagementSection.tsx    # Main container component
│   ├── SimDetailsCard.tsx          # SIM information display
│   ├── DataUsageChart.tsx          # Usage visualization
│   ├── SimActions.tsx              # Action buttons and confirmations
│   └── TopUpModal.tsx              # Data top-up interface
└── index.ts                        # Exports
```

### Features
- **Responsive Design**: Works on desktop and mobile
- **Real-time Updates**: Automatic refresh after actions
- **Visual Feedback**: Progress bars, status indicators, loading states
- **Error Handling**: Comprehensive error messages and recovery
- **Accessibility**: Proper ARIA labels and keyboard navigation

## 🗄️ Required Salesforce Custom Fields

To enable proper SIM data tracking in Salesforce, add these custom fields:

### On Service/Product Object

```sql
-- Core SIM Identifiers
Freebit_Account__c (Text, 15) - Freebit account identifier (phone number)
Freebit_MSISDN__c (Text, 15) - Phone number/MSISDN
Freebit_ICCID__c (Text, 22) - SIM card identifier (physical SIMs)
Freebit_EID__c (Text, 32) - eSIM identifier (eSIMs only)
Freebit_IMSI__c (Text, 15) - International Mobile Subscriber Identity

-- Service Information
Freebit_Plan_Code__c (Text, 20) - Current Freebit plan code
Freebit_Status__c (Picklist) - active, suspended, cancelled, pending
Freebit_SIM_Type__c (Picklist) - physical, esim
Freebit_SIM_Size__c (Picklist) - standard, nano, micro, esim

-- Service Features
Freebit_Has_Voice__c (Checkbox) - Voice service enabled
Freebit_Has_SMS__c (Checkbox) - SMS service enabled
Freebit_IPv4__c (Text, 15) - Assigned IPv4 address
Freebit_IPv6__c (Text, 39) - Assigned IPv6 address

-- Data Tracking
Freebit_Remaining_Quota_KB__c (Number) - Current remaining data in KB
Freebit_Remaining_Quota_MB__c (Formula) - Freebit_Remaining_Quota_KB__c / 1024
Freebit_Last_Usage_Sync__c (DateTime) - Last usage data sync
Freebit_Is_Blacklisted__c (Checkbox) - Service restriction status

-- Service Dates
Freebit_Service_Start__c (Date) - Service activation date
Freebit_Last_Sync__c (DateTime) - Last sync with Freebit API

-- Pending Operations
Freebit_Pending_Operation__c (Text, 50) - Scheduled operation type
Freebit_Operation_Date__c (Date) - Scheduled operation date
```

### Optional: Dedicated SIM Management Object

For detailed tracking, create a custom object `SIM_Management__c`:

```sql
SIM_Management__c
├── Service__c (Lookup to Service) - Related service record
├── Freebit_Account__c (Text, 15) - Freebit account identifier
├── Action_Type__c (Picklist) - topup, cancel, reissue, plan_change
├── Action_Date__c (DateTime) - When action was performed
├── Amount_MB__c (Number) - Data amount (for top-ups)
├── Previous_Plan__c (Text, 20) - Previous plan (for plan changes)
├── New_Plan__c (Text, 20) - New plan (for plan changes)
├── Status__c (Picklist) - success, failed, pending
├── Error_Message__c (Long Text) - Error details if failed
├── Scheduled_Date__c (Date) - For scheduled operations
├── Campaign_Code__c (Text, 20) - Campaign code used
└── Notes__c (Long Text) - Additional notes
```

## 🚀 Deployment Configuration

### Environment Variables (BFF)

Add these to your `.env` file:

```bash
# Freebit API Configuration
# Production URL
FREEBIT_BASE_URL=https://i1.mvno.net/emptool/api
# Test URL (for development/testing)
# FREEBIT_BASE_URL=https://i1-q.mvno.net/emptool/api

FREEBIT_OEM_ID=PASI
FREEBIT_OEM_KEY=your_32_char_oem_key_from_freebit
FREEBIT_TIMEOUT=30000
FREEBIT_RETRY_ATTEMPTS=3
```

### Module Registration

Ensure the Freebit module is imported in your main app module:

```typescript
// apps/bff/src/app.module.ts
import { FreebititModule } from './vendors/freebit/freebit.module';

@Module({
  imports: [
    // ... other modules
    FreebititModule,
  ],
})
export class AppModule {}
```

## 🧪 Testing

### Backend Testing
```bash
# Test Freebit API connectivity
curl -X POST http://localhost:3001/api/subscriptions/{id}/sim/details \
  -H "Authorization: Bearer {token}"

# Test data top-up
curl -X POST http://localhost:3001/api/subscriptions/{id}/sim/top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"quotaMb": 1024}'
```

### Frontend Testing
1. Navigate to a SIM subscription detail page
2. Verify SIM management section appears
3. Test top-up modal with different amounts
4. Test eSIM reissue (if applicable)
5. Verify error handling with invalid inputs

## 🔒 Security Considerations

1. **API Authentication**: Freebit auth keys are securely cached and refreshed
2. **Input Validation**: All user inputs are validated on both frontend and backend
3. **Rate Limiting**: Implement rate limiting for SIM management operations
4. **Audit Logging**: All SIM actions are logged with user context
5. **Error Handling**: Sensitive error details are not exposed to users

## 📊 Monitoring & Analytics

### Key Metrics to Track
- SIM management API response times
- Top-up success/failure rates
- Most popular data amounts
- Error rates by operation type
- Usage by SIM type (physical vs eSIM)

### Recommended Dashboards
1. **SIM Operations Dashboard**
   - Daily/weekly top-up volumes
   - Plan change requests
   - Cancellation rates
   - Error tracking

2. **User Engagement Dashboard**
   - SIM management feature usage
   - Self-service vs support ticket ratio
   - User satisfaction metrics

## 🆘 Troubleshooting

### Common Issues

**1. "This subscription is not a SIM service"**
- Check if subscription product name contains "sim"
- Verify subscription has proper SIM identifiers

**2. "SIM account identifier not found"**
- Ensure subscription.domain contains valid phone number
- Check WHMCS service configuration

**3. Freebit API authentication failures**
- Verify OEM ID and key configuration
- Check Freebit API endpoint accessibility
- Review authentication token expiry

**4. Data usage not updating**
- Check Freebit API rate limits
- Verify account identifier format
- Review sync job logs

### Support Contacts
- **Freebit API Issues**: Contact Freebit technical support
- **Portal Issues**: Check application logs and error tracking
- **Salesforce Integration**: Review field mapping and data sync jobs

## 🔄 Future Enhancements

### Planned Features
1. **Voice Options Management**
   - Enable/disable voicemail
   - Configure call forwarding
   - International calling settings

2. **Usage Analytics**
   - Monthly usage trends
   - Cost optimization recommendations
   - Usage prediction and alerts

3. **Bulk Operations**
   - Multi-SIM management for business accounts
   - Bulk data top-ups
   - Group plan management

4. **Advanced Notifications**
   - Low data alerts
   - Usage milestone notifications
   - Plan recommendation engine

### Integration Opportunities
1. **Payment Integration**: Direct payment for top-ups
2. **Support Integration**: Create support cases from SIM issues
3. **Billing Integration**: Usage-based billing reconciliation
4. **Analytics Integration**: Usage data for business intelligence

---

## ✅ Implementation Complete

The Freebit SIM management system is now fully implemented and ready for deployment. The system provides customers with complete self-service SIM management capabilities while maintaining proper data tracking and security standards.

**Next Steps:**
1. Configure Freebit API credentials
2. Add Salesforce custom fields
3. Test with sample SIM subscriptions
4. Train customer support team
5. Deploy to production

For technical support or questions about this implementation, refer to the troubleshooting section above or contact the development team.