fleeta-api-lib/README.md

A comprehensive library for fleet management applications - API, Auth, Device management

# FleetA API Library (fleeta-api-lib)

[![npm version](https://badge.fury.io/js/fleeta-api-lib.svg)](https://badge.fury.io/js/fleeta-api-lib)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive TypeScript library for BlackVue FleetA fleet management applications, providing authentication, device management, real-time GPS tracking, live streaming, and user management capabilities.

## 📦 Installation

```bash
npm install fleeta-api-lib
```

## 🚀 Quick Start

```typescript
import { 
  useAuthStore,
  login,
  getDeviceList,
  createBasicGpsProvider,
  EventWebSocketSDK
} from 'fleeta-api-lib';

// 1. Authentication
await login({ email: 'user@example.com', password: 'password' });

// 2. Device Management
const devices = await getDeviceList();

// 3. Real-time GPS Data
const gpsProvider = createBasicGpsProvider();
gpsProvider.initialize();
gpsProvider.connectWebSocket();

// 4. WebPush Events
const eventSDK = new EventWebSocketSDK();
eventSDK.initialize();
eventSDK.connect();
```

## 🏗️ Core Modules

### 🔐 Authentication Module
- JWT-based authentication with automatic token management
- Secure login/logout functionality
- Password reset capabilities
- Zustand-based state management

```typescript
import { login, logout, resetPassword, useAuthStore } from 'fleeta-api-lib';

// Login
await login({ email: 'user@example.com', password: 'password' });

// Access auth state
const { isAuthenticated, userToken, subscribeInfo } = useAuthStore();

// Logout
await logout();
```

### 📱 Device Management Module
- Complete device lifecycle management
- Device registration (WiFi/Cloud categories)
- Firmware settings configuration
- Live event upload settings
- Device status monitoring

```typescript
import { 
  getDeviceList, 
  quickRegisterDevice, 
  getFirmwareSettings,
  setFirmwareSettings
} from 'fleeta-api-lib';

// Get device list with grouping
const response = await getDeviceList();
const { groups, statistics } = response.groupedData;

// Quick device registration
await quickRegisterDevice('7XBPK2N7E01', 'wifi');

// Firmware settings
const settings = await getFirmwareSettings({ psn: '7XBPK2N7E01' });
```

### 🌍 Real-time GPS Tracking
- WebSocket-based real-time GPS data
- Multiple data provider factories
- Advanced filtering and caching
- Zone-based and device-specific tracking

```typescript
import { 
  createMapGpsProvider,
  createDashboardGpsProvider 
} from 'fleeta-api-lib';

// Create optimized GPS provider for maps
const gpsProvider = createMapGpsProvider();
await gpsProvider.initialize();

// Register for GPS updates
gpsProvider.registerUpdateCallback((devices) => {
  console.log('GPS Update:', devices.length, 'devices');
});

// Connect and request data
gpsProvider.connectWebSocket();
await gpsProvider.requestGpsPsnsMyDevices();
```

### 📺 Live Streaming (WebRTC)
- Real-time video streaming
- Multi-channel support (Front/Rear/Interior/Exterior)
- Two-way audio communication
- Quality adaptation and statistics

```typescript
import { 
  createWebRTCProvider,
  startLiveStreamingWorkflow 
} from 'fleeta-api-lib';

// Create WebRTC provider
const provider = createWebRTCProvider({
  deviceId: '7XBPK2N7E01',
  channel: 'front',
  enableStats: true
});

// Set up event callbacks
provider.setCallbacks({
  onStreamReceived: (stream) => {
    videoElement.srcObject = stream;
  },
  onError: (error) => console.error('Stream error:', error)
});

// Connect to live stream
await provider.connect();
```

### 🔔 Real-time Event Notifications
- WebPush event monitoring
- 30+ event types (driving, parking, system)
- PSN filtering and categorization
- Image and file attachments

```typescript
import { EventWebSocketSDK, WEBPUSH_EVENT_DESCRIPTIONS } from 'fleeta-api-lib';

const eventSDK = new EventWebSocketSDK();

// Set up event handlers
eventSDK.on('webpush', (message) => {
  console.log('Event received:', message.code, message.message);
  
  if (message.image) {
    console.log('Event image:', message.image);
  }
});

eventSDK.initialize();
eventSDK.connect();
```

### 👥 User Management
- User invitation system (SubMaster/User roles)
- Permission management
- Member list and deletion
- Role-based access control

```typescript
import { 
  inviteSubMaster, 
  inviteUser,
  getInviteMemberList,
  getMasterPermissions 
} from 'fleeta-api-lib';

// Invite users
await inviteSubMaster('submaster@company.com');
await inviteUser('driver@company.com');

// Get invited members
const members = await getInviteMemberList({ searchKey: '' });

// Check permissions
const permissions = await getMasterPermissions();
```

### 🗂️ Group Management
- Group creation and deletion
- Device assignment to groups
- SubMaster group assignment
- Hierarchical access control

```typescript
import { 
  addGroup,
  addDevicesToGroup,
  assignSubMasterToGroup 
} from 'fleeta-api-lib';

// Create groups
await addGroup({ groupNameList: ['Fleet Alpha', 'Fleet Beta'] });

// Assign devices to group
await addDevicesToGroup({
  Add: [{
    PSN: '7XBPK2N7E01',
    GroupID: 'group_001',
    GroupName: 'Fleet Alpha'
  }]
});
```

## 🌟 Advanced Features

### Multi-Device Provider
Manage multiple device streams simultaneously with automatic quality adaptation.

```typescript
import { createMultiDeviceProvider } from 'fleeta-api-lib';

const multiProvider = await createMultiDeviceProvider(9); // 3x3 grid

// Add devices
const device1 = await multiProvider.addDevice('PSN001', 'front');
const device2 = await multiProvider.addDevice('PSN002', 'rear');

// Start voice communication
await multiProvider.startVoiceComm('PSN001');
```

### GPS Data Manager
Centralized GPS data management with multiple providers.

```typescript
import { createGpsDataManager } from 'fleeta-api-lib';

const manager = createGpsDataManager();
await manager.initialize();

// Create multiple providers
const mapProvider = manager.createProvider('map', { enableCaching: true });
const dashProvider = manager.createProvider('dashboard', { enableBatching: true });

// Global data callback
manager.registerDataCallback((allData) => {
  console.log('All GPS data:', allData);
});
```

## 🔧 Configuration

### Environment Variables

```env
VITE_API_GATEWAY=https://your-api-gateway.com
VITE_IOT_API_GATEWAY=https://your-iot-gateway.com
VITE_GPS_WEBSOCKET_URL=wss://your-gps-websocket.com
VITE_EVENT_WEBSOCKET_URL=wss://your-event-websocket.com
```

### API Endpoint Initialization

```typescript
import { useApiEndpointStore } from 'fleeta-api-lib';

// Initialize endpoints (typically in main.tsx)
useApiEndpointStore.getState().setConfig({
  apiGateway: import.meta.env.VITE_API_GATEWAY,
  iotApiGateway: import.meta.env.VITE_IOT_API_GATEWAY,
  gpsWebSocketUrl: import.meta.env.VITE_GPS_WEBSOCKET_URL,
  eventWebSocketUrl: import.meta.env.VITE_EVENT_WEBSOCKET_URL
});
```

## 📊 Type Safety

This library is built with TypeScript and provides comprehensive type definitions:

```typescript
import type { 
  DeviceListResponse,
  DeviceInfo,
  WebPushMessage,
  GpsDataProviderConfig,
  MultiDeviceProviderConfig 
} from 'fleeta-api-lib';
```

## 🚀 Version History

### v1.6.7 (Latest)
- **🐛 Bug Fix**: Fixed DeviceListPage component error where `groups` property was undefined
- **🔧 API Consistency**: Corrected property access from `groups` to `devicesByGroup` in DeviceListResponse
- **💎 UI Stability**: Enhanced error handling for device list rendering
- **🎯 Data Structure Alignment**: Ensured proper access to grouped device data structure

### v1.6.6 (Latest)
- **📝 Type Definition Enhancement**: Added missing GroupDeviceData type definition to complete data structure
- **📤 Export Completeness**: Full export of GroupDeviceData type across all module levels
- **🔧 TypeScript Compatibility**: Fixed TypeScript compilation errors in device grouping module
- **🎯 Data Structure Integrity**: Ensured both group-centered and device-centered data structures are properly typed
- **💎 Developer Experience**: Complete TypeScript support for all grouping functionality

### v1.6.5 (Latest)
- **🎯 Data Structure Enhancement**: Restructured DeviceListResponse groupedData for symmetric design
- **🔄 Interface Symmetry**: Renamed groups→devicesByGroup and deviceGroups→groupsByDevice
- **📊 Type Consistency**: Enhanced DeviceGroupData with complete device information via device: DeviceInfo property
- **🧹 Code Quality**: Removed UI state (isExpanded) from data models for better separation of concerns
- **💎 Developer Experience**: Improved data structure clarity with symmetric naming and consistent typing

### v1.6.4 (Latest)
- **🛡️ Data Quality**: Enhanced device grouping with duplicate prevention in groupDevicesByGroup function
- **🔧 Bug Fix**: Prevented duplicate devices from being added to the same group
- **📦 Data Integrity**: Added PSN tracking with Set-based duplicate detection
- **💎 Code Quality**: Improved data consistency in device group management operations

### v1.6.3 (Latest)
- **🔧 API Enhancement**: Enhanced LoginParams interface to support all API specification fields
- **🛡️ Parameter Validation**: Added comprehensive validation for OAuth login types and required parameters
- **📦 Backward Compatibility**: Maintained existing simple login({ email, password }) usage pattern
- **🎯 OAuth Support**: Full support for Google/Apple login with oauthToken parameter
- **🌐 Localization**: Added mobileLang parameter support for alarm language settings
- **💎 Code Quality**: Improved login function with smart defaults and flexible parameter handling

### v1.6.1 (Latest)
- **🐛 Bug Fixes**: Fixed TypeScript compilation errors in auth module
- **🔧 Code Quality**: Enhanced utility function implementations (getBrowserName, getTimezoneOffsetMinutes)
- **📦 Type Safety**: Improved SubscribeInfo and ServerConfig type exports
- **💎 Developer Experience**: Resolved missing dependency issues for confirmUser() function

### v1.5.2 (Latest)
- **🧹 Code Cleanup**: Removed unnecessary deviceAssignmentSummary from Enhanced Group Device Response
- **📦 Type Safety**: Simplified device mapping data structure for better performance 
- **🎯 API Streamlining**: Enhanced Group Device API now focuses only on essential mapping data
- **💎 Code Quality**: Cleaner Group API structure with reduced complexity

### v1.5.1 (Latest)
- **🔧 API Field Consistency**: Fixed AddDevicesToGroupParams field names to match server API requirements
- **📦 Type Safety**: Updated GroupID field naming across Device Group Assignment APIs
- **🎯 API Compatibility**: Enhanced type-to-implementation alignment for PushMasterGroup API calls
- **💎 Code Quality**: Improved consistency between TypeScript types and actual API payload structure

### v1.5.0 (Latest)
- **🎯 Minor Release**: Enhanced data filtering and API consistency improvements
- **🛡️ Data Quality**: Advanced filtering for GroupAllocationDevice and Users data
- **🔧 API Enhancement**: Improved Group API field consistency with server requirements
- **📦 Type Safety**: Enhanced parameter validation across all Group APIs
- **💎 Code Quality**: Production-ready builds with optimized data processing

### v1.4.22 (Latest)
- **🧹 Code Cleanup**: Removed all console.log statements from Group and Device API modules
- **📦 Production Ready**: Clean library builds without development logging
- **🎯 Performance**: Optimized for production environments with minimal debug output
- **💎 Code Quality**: Enhanced maintainability with cleaner codebase

### v1.4.21 (Latest)
- **🔧 API Field Consistency**: Fixed `AssignUserToDeviceParams.groupId` → `GroupID` for API compatibility
- **🛡️ Parameter Validation**: Enhanced group user assignment API parameter validation
- **📦 Type Safety**: Aligned parameter field names with server API requirements
- **💎 Code Quality**: Improved Group API consistency across all user assignment operations

### v1.4.20 (Latest)
- **🔧 API Response Structure**: Fixed DeviceListResponse type definition to match actual API structure
- **🐛 Bug Fix**: Corrected getDeviceList response mapping from flat structure to nested response object
- **💎 Type Safety**: Enhanced TypeScript type consistency across Device API and Mock API
- **📦 Structure Alignment**: Unified response structure for real and mock device data

### v1.4.19
- **🎯 Type Consistency**: Simplified DeviceListResponse interface by removing unused nested response structure
- **🔧 API Field Alignment**: Fixed AssignSubMasterToGroupParams.groupId → groupManagementID for API compatibility
- **📦 Type Safety**: Enhanced parameter validation with correct field names
- **💎 Code Quality**: Improved type-to-implementation alignment across Group APIs

### v1.4.18
- **🧹 Code Cleanup**: Removed all console logs from Users API module for cleaner production builds
- **🔧 API Consistency**: Fixed `AssignSubMasterToGroupParams.groupId` → `groupManagementID` for proper API compatibility
- **📦 Type Safety**: Enhanced parameter validation and field name consistency
- **🎯 Production Ready**: Eliminated development logging from production library builds

### v1.4.17
- **🔧 Type Export Completeness**: Fixed missing UserPermissions type exports in main library index
- **📦 Enhanced Type Safety**: Added all target user permission types (GetTargetUserPermissionsParams/Response, SetTargetUserPermissionsParams/Response)
- **🛡️ Error Message Coverage**: Exported all permission-related error message constants
- **🎯 Developer Experience**: Complete TypeScript support for all Users API functionality

### v1.4.13
- **🔧 API Consistency**: Standardized all group field names to `groupId`/`groupIds`
- **🎯 Type Safety**: Fixed TypeScript errors and improved type consistency
- **📝 Field Unification**: Eliminated `groupManagementID`, `GroupID`, `groupDeleteIDList` variations
- **🚀 Developer Experience**: Consistent field naming across Device, GPS, and Group APIs

### v1.4.12
- **🛡️ Parameter Safety**: Enhanced group API parameter validation
- **🔧 API Enhancement**: Improved group management functionality

### v1.4.11 (Latest)
- **🛡️ Type Completeness**: All required Device API types now fully exported
- **🔧 API Enhancement**: Added Firmware Settings and Live Event Upload Settings types
- **📦 Developer Experience**: Complete TypeScript support for all Device APIs
- **🎯 Type Safety**: Enhanced type definitions for better IDE autocomplete

### v1.4.10
- **🛡️ Parameter Safety**: Fixed duplicate parameter issues across all Device APIs
- **🔧 API Cleanup**: Removed redundant parameters from function signatures
- **🎯 Consistency**: Unified parameter handling using AuthStore automation
- **💎 Code Quality**: Eliminated TypeScript compilation errors

### v1.4.9
- **🛡️ PSN Type Safety**: Enhanced PSN parameter validation across all Device APIs
- **⚡ Performance**: `quickRegisterDevice` now uses direct API calls
- **🐛 Bug Fix**: Eliminated `TypeError: psn.trim is not a function`
- **🔧 Stability**: Improved runtime error handling

### v1.4.8
- **🛡️ Security**: Enhanced PSN validation in 9 device API functions
- **📝 Docs**: Improved error messages for better debugging

### v1.4.7
- **🔧 API**: Initial PSN safety improvements
- **📈 Performance**: Optimized device management workflows

## 🧪 Testing

```bash
# Install dependencies
npm install

# Run tests (if available)
npm test

# Build library
npm run build:lib

# Type checking
npm run build:types
```

## 📚 API Reference

### Authentication APIs
- `login(params)` - User authentication
- `logout()` - User logout
- `registerUser(params)` - User account registration
- `confirmUser(params)` - Email confirmation with auto-login
- `registerUser(params)` - User account registration
- `confirmUser(params)` - Account confirmation with auto-login
- `resetPassword(email)` - Password reset
- `useAuthStore` - Auth state management

### Device APIs  
- `getDeviceList(params?)` - Get device list with grouping
- `quickRegisterDevice(psn, category)` - Fast device registration
- `updateDevice(params)` - Update device configuration
- `deleteDevice(params)` - Remove device
- `getFirmwareSettings(params)` - Get firmware configuration
- `setFirmwareSettings(params)` - Update firmware settings

### GPS APIs
- `createBasicGpsProvider()` - Basic GPS data provider
- `createMapGpsProvider()` - Map-optimized provider
- `createDashboardGpsProvider()` - Dashboard-optimized provider
- `GpsWebSocketSDK` - Low-level GPS WebSocket

### Live Streaming APIs
- `createWebRTCProvider(config)` - WebRTC video provider
- `startLiveStreamingWorkflow()` - Complete streaming setup
- `playLiveView(params)` - Start live view
- `stopLiveView(params)` - Stop live view
- `startTwoWayAudio(params)` - Enable two-way audio

### Event APIs
- `EventWebSocketSDK` - WebPush event monitoring
- `WEBPUSH_EVENT_DESCRIPTIONS` - Event type descriptions
- `isImageIncludedEvent()` - Check if event includes image

### User Management APIs
- `inviteSubMaster(email)` - Invite SubMaster user
- `inviteUser(email)` - Invite regular user
- `getInviteMemberList(params)` - Get invited members
- `deleteMember(params)` - Remove member

### Group Management APIs
- `addGroup(params)` - Create groups
- `getGroupList(params)` - Get group list
- `deleteGroup(params)` - Delete groups
- `addDevicesToGroup(params)` - Assign devices to groups
- `assignSubMasterToGroup(params)` - Assign SubMaster to group

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Commit changes: `git commit -am 'Add new feature'`
4. Push to branch: `git push origin feature/new-feature`
5. Submit a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/hurfoong/Fleeta-Components-API/issues)
- **Documentation**: Check the TypeScript definitions in your IDE
- **Examples**: See the `/src/pages` directory for usage examples

## 🏢 About FleetA

FleetA is a comprehensive fleet management solution providing:
- **Real-time Vehicle Tracking** 
- **Live Video Streaming**
- **Event-based Monitoring**
- **Driver Behavior Analysis**
- **Fleet Analytics & Reporting**

Built for modern fleet operations with enterprise-grade security and scalability.

---

**Made with ❤️ by the FleetA Team**