🚀 FleetA Library

A comprehensive library for fleet management applications. Features authentication, API client, device management, and data storage for BlackVue Fleeta ecosystem.

🚀 Quick Start

Installation

npm install fleeta-lib

Peer Dependencies

Install required peer dependencies:

npm install react react-dom

Basic Usage

import React from 'react';
import { 
  login, 
  logout, 
  getDeviceList, 
  useAuthStore,
  useApiEndpointStore 
} from 'fleeta-lib';

function MyFleetApp() {
  const { isAuthenticated, userToken } = useAuthStore();
  
  const handleLogin = async () => {
    await login({ 
      email: '[email protected]', 
      password: 'password' 
    });
  };
  
  const handleGetDevices = async () => {
    const deviceList = await getDeviceList();
    console.log('Devices:', deviceList);
  };
  
  return (
    <div>
      {!isAuthenticated ? (
        <button onClick={handleLogin}>Login</button>
      ) : (
        <button onClick={handleGetDevices}>Get Devices</button>
      )}
    </div>
  );
}

✨ Features

🔐 Authentication Module

Complete authentication solution for BlackVue Fleeta:

• Login/Logout - Email/password authentication

• Password Reset - Reset password functionality

• Auth Store - Zustand-based state management

• Auth Utils - Helper functions and type checking

• 🔐 Authentication - Complete login/logout system for BlackVue Fleeta

• 📱 Device Management - Device listing, grouping, and statistics

• 🔗 API Client - HTTP client with authentication headers

• 🏪 State Management - Zustand stores for auth and API endpoints

• 🎨 TypeScript - Full type safety and excellent DX

• 🌳 Tree Shaking - Import only what you need

📱 Device Management Module

Advanced device management for BlackVue fleet:

• Device List API - Get devices with grouping and statistics
• Mock Data - Testing with combined mock + real data
• Device Filtering - Search, filter by status, mode, etc.
• Group Management - Organize devices into groups

🌐 API Management Module

Centralized API endpoint management:

• Endpoint Configuration - Manage API URLs
• Environment Variables - Load from .env files
• Validation - Ensure endpoints are configured properly

🔧 Environment Setup

Set up your environment variables:

# .env file
VITE_API_GATEWAY=https://your-api-gateway.com
VITE_IOT_API_GATEWAY=https://your-iot-api-gateway.com

📖 API Documentation

Authentication

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

// Login
await login({ 
  email: '[email protected]', 
  password: 'password' 
});

// Logout
await logout();

// Password Reset
const result = await resetPassword('[email protected]');

// Use Auth Store
const { isAuthenticated, userToken, subscribeInfo } = useAuthStore();

Device Management

import { getDeviceList, getMockDeviceList, useAuthStore } from 'fleeta-lib';

// Get real device list (requires authentication)
const deviceList = await getDeviceList();

// Get mock + real device list
const mockDeviceList = await getMockDeviceList();

// Use with authentication
const { isAuthenticated } = useAuthStore();
if (isAuthenticated) {
  const devices = await getDeviceList();
}

API Endpoint Management

import { 
  getApiGateway, 
  getIotApiGateway,
  useApiEndpointStore 
} from 'fleeta-lib';

// Get configured endpoints
const apiUrl = getApiGateway();
const iotUrl = getIotApiGateway();

// Configure endpoints (usually in main.tsx)
useApiEndpointStore.getState().setConfig({
  apiGateway: 'https://api.example.com',
  iotApiGateway: 'https://iot.example.com'
});

📡 GPS Data Provider

Advanced GPS data management system for real-time device tracking:

import { 
  createBasicGpsProvider, 
  useGpsDataStream,
  RealTimeGpsMap 
} from 'fleeta-components';

const provider = createBasicGpsProvider(userEmail, gpsSDK);

const { optimizedDevices, selectedDevice, selectDevice } = useGpsDataStream({
  provider,
  subscriberId: 'my-map',
  enableOptimization: true
});

<RealTimeGpsMap 
  devices={optimizedDevices}
  selectedDevice={selectedDevice}
  onDeviceSelect={selectDevice}
/>

Key Features:

• 🔄 Smart Data Processing: Filters unnecessary updates
• ⚡ Performance Optimized: Map-rendering optimizations
• 📊 Multi-Subscriber Support: Share data across components
• 💾 Built-in Caching: LRU cache with memory management
• 🎯 Flexible Filtering: PSN lists, bounding boxes, status filters

📖 Documentation

• Installation Guide
• API Documentation
• Usage Examples
• GPS Data Provider Guide
• Troubleshooting

🌳 Tree Shaking

Import only what you need to reduce bundle size:

// Import authentication only
import { login, logout } from 'fleeta-lib';

// Import device management only
import { getDeviceList } from 'fleeta-lib';

// Import stores only
import { useAuthStore, useApiEndpointStore } from 'fleeta-lib';

// Import only types (zero runtime cost)
import type { AuthConfig, DeviceListItem } from 'fleeta-lib';

Bundle size savings:

• Authentication only: ~60% smaller
• Device API only: ~70% smaller
• Stores only: ~80% smaller
• Types only: 100% smaller (no runtime cost)

Import VideoPlayer and WebRTC components

// Import VideoPlayer for recorded videos
import { VideoPlayer } from 'fleeta-components';

// Import WebRTC components for live streaming  
import { WebRTCPlayer, createWebRTCProvider } from 'fleeta-components';

// Import utilities
import { parseGpsData } from 'fleeta-components';

📖 Documentation

• Installation Guide
• API Documentation
• Usage Examples
• Troubleshooting

🔧 Configuration

Environment Variables

Set up required environment variables:

VITE_API_GATEWAY=https://your-api-gateway.com
VITE_IOT_API_GATEWAY=https://your-iot-api-gateway.com

Initialize in your app

// main.tsx or App.tsx
import { useApiEndpointStore } from 'fleeta-lib';

// Initialize API endpoints
useApiEndpointStore.getState().setConfig({
  apiGateway: import.meta.env.VITE_API_GATEWAY,
  iotApiGateway: import.meta.env.VITE_IOT_API_GATEWAY
});

Components

VideoPlayer

The main video player component with integrated GPS mapping and sensor data visualization.

interface VideoPlayerProps {
  // Video source and configuration
  videoUrl: string | null;
  
  enableMetadataParsing?: boolean;
  showMap?: boolean;
  
  // GPS and sensor data (external)
  gpsPoints?: GpsPoint[] | null;
  sensorData?: IAccel[] | null;
  
  // Player configuration
  autoPlay?: boolean;
  showControls?: boolean;
  showMap?: boolean;
  speedUnit?: 'km/h' | 'mph';
  
  // Event callbacks
  onTimeUpdate?: (currentTime: number) => void;
  onDurationChange?: (duration: number) => void;
  onPlay?: () => void;
  onPause?: () => void;
  onError?: (error: string) => void;
  
  // Styling
  className?: string;
}

Example:

<VideoPlayer
  videoUrl="https://example.com/video.mp4"
  enableMetadataParsing={true}
  autoPlay={true}
  showMap={true}
  speedUnit="km/h"
  onTimeUpdate={(time) => console.log('Current time:', time)}
  onError={(error) => console.error('Video error:', error)}
/>

Key Features:

• 🎬 Advanced video controls with frame stepping
• 🗺️ Integrated GPS map with route visualization
• 📊 Real-time G-sensor data display
• 🎨 Dark/light mode support

MapComponent

Displays GPS tracking data on an interactive map.

interface MapComponentProps {
  gpsPoints?: GpsPoint[];
  currentTime?: number;
  sensorData?: IAccel[];
  speedUnit?: 'km/h' | 'mph';
  mapStyle?: 'streets' | 'satellite' | 'outdoors' | 'light' | 'dark';
  height?: string;
  className?: string;
}

Example:

<MapComponent
  gpsPoints={gpsData}
  currentTime={30}
  speedUnit="mph"
  mapStyle="satellite"
  height="300px"
/>

EventComponent

Visualizes G-sensor acceleration data.

interface EventComponentProps {
  sensorData?: IAccel[];
  currentTime?: number;
  videoDuration?: number;
  height?: string;
  className?: string;
}

Example:

<EventComponent
  sensorData={accelerationData}
  currentTime={30}
  videoDuration={120}
  height="100px"
/>

Utilities

GPS Data Parsing

import { parseGpsData, GpsParsingStatus } from 'fleeta-video-player';

const result = parseGpsData(base64Data);

if (result.status === GpsParsingStatus.SUCCESS) {
  console.log('GPS points:', result.points);
}

Sensor Data Parsing

import { parseSensorData, SensorParsingStatus } from 'fleeta-video-player';

const result = parseSensorData(base64Data);

if (result.status === SensorParsingStatus.SUCCESS) {
  console.log('Sensor data:', result.points);
}

MP4 Metadata Extraction

import { fetchAndParseMP4 } from 'fleeta-video-player';

const metadata = await fetchAndParseMP4('https://example.com/video.mp4');

console.log('GPS data:', metadata.gps);
console.log('Sensor data:', metadata.sensor);
console.log('Thumbnail:', metadata.thumbnail);

🎨 Styling

FleetA VideoPlayer uses Tailwind CSS classes. You can:

1. Use default styles - Include the CSS bundle
2. Custom styling - Override with your own CSS
3. Tailwind integration - Use Tailwind classes directly

// Include component styles
import 'fleeta-components/dist/style.css';

// Custom styling
<VideoPlayer 
  className="my-custom-player border-2 border-blue-500"
  videoUrl={url}
/>

🌳 Tree Shaking

Import only what you need to reduce bundle size:

// Import VideoPlayer (includes all sub-components)
import { VideoPlayer } from 'fleeta-components';

// Import only utilities
import { parseGpsData } from 'fleeta-components';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-components';

Bundle size savings:

• VideoPlayer only: ~40% smaller
• GPS parsing only: ~80% smaller
• Utilities only: ~90% smaller
• Types only: 100% smaller (no runtime cost)

🔧 Configuration

Environment Variables

Set up Mapbox for map functionality:

VITE_MAPBOX_ACCESS_TOKEN=your_token_here

TypeScript

FleetA Video Player includes complete TypeScript definitions:

import type { 
  VideoPlayerProps,
  GpsPoint,
  IAccel,
  ExtractedMetadata 
} from 'fleeta-components';

📱 Responsive Design

The components are fully responsive and work on all screen sizes:

<div className="w-full h-screen md:h-96">
  <VideoPlayer
    videoUrl={url}
    showMap={true}
    className="w-full h-full"
  />
</div>

🚗 Key Features

GPS Tracking

• Real-time vehicle position
• Route visualization
• Speed display (km/h or mph)
• Heading direction

G-Sensor Visualization

• Acceleration visualization
• Event detection
• Synchronized with video playback

MP4 Metadata

• Automatic data extraction
• GPS and sensor parsing
• Thumbnail generation

🔍 Advanced Examples

Custom GPS Data

const customGpsPoints: GpsPoint[] = [
  {
    timestamp: 0,
    lat: 37.7749,
    lng: -122.4194,
    relativeTime: 0,
    speedKmh: 50,
    speedKnots: 27,
    course: 90
  }
];

<VideoPlayer
  videoUrl={url}
  gpsPoints={customGpsPoints}
  showMap={true}
/>

Event Handling

<VideoPlayer 
  videoUrl={url}
  onTimeUpdate={(time) => {
    console.log(`Video time: ${time}s`);
  }}
  onPlay={() => {
    console.log('Video started playing');
  }}
  onError={(error) => {
    console.error('Playback error:', error);
  }}
/>

Dark Mode

// Manual dark mode
<div className="dark">
  <VideoPlayer 
    videoUrl={url}
    mapStyle="dark"
  />
</div>

🛠️ Development

Building from Source

git clone https://github.com/fleeta-team/fleeta-components.git
cd fleeta-components
npm install
npm run build:lib

Running Tests

npm run quality:full
npm run validate:full

📄 Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📝 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 API Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🎬 FleetA VideoPlayer - Complete Video Playback Solution for Fleet Management