fleeta-api-lib

v1.6.7

Published

3 months ago

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

0High
0Medium
0Low

hhur

react fleet-management api-client authentication device-management gps typescript vehicle-tracking blackvue fleeta

FleetA API Library (fleeta-api-lib)

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

npm install fleeta-api-lib

🚀 Quick Start

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

// 1. Authentication
await login({ email: '[email protected]', 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

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

// Login
await login({ email: '[email protected]', 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

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

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

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

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

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

// Invite users
await inviteSubMaster('[email protected]');
await inviteUser('[email protected]');

// 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

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.

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.

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

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

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:

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

# 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

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Commit changes: git commit -am 'Add new feature'
Push to branch: git push origin feature/new-feature
Submit a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Issues: GitHub 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