Skip to main content

JavaScript/TypeScript SDK

The official JS/TS SDK for Vehk Axle — v2.0 (vehk-axle): telemetry, ML predictions, GPS tracking, and device APIs over /api/external/*.

Installation​

npm install vehk-axle
# or
yarn add vehk-axle

Requirements: Node.js 14+ or modern browser

Quick Start​

import { VehkClient } from 'vehk-axle';

// Initialize client
const client = new VehkClient('vehk_your_api_key');

// Send telemetry
await client.telemetry.send({
    vehicle_id: 'VH-001',
    sensor_data: { speed: 65, rpm: 2500 }
});

// Get prediction
const prediction = await client.predictions.get('VH-001', { speed: 65, rpm: 2500 });
console.log(`Health: ${prediction.health_score}%`);

await client.tracking.send({
    device_id: '862061048760001',
    latitude: 12.9716,
    longitude: 77.5946,
    speed: 45.2,
    ignition: true,
});

Client configuration​

import { VehkClient } from 'vehk-axle';

const client = new VehkClient(
    'vehk_your_api_key',
    'https://vehk-api.bravedune-34ccdec3.centralindia.azurecontainerapps.io', // optional override
);

Requests send X-API-Key. Key scopes must match each call (telemetry:write, tracking:write, predict, vehicles:read, devices:read). Register devices in Axle before tracking — see Device Configurator.

TypeScript types​

The SDK is fully typed. Import types as needed:

import {
    VehkClient,
    TelemetryData,
    TrackingData,
    DeviceLocation,
    Prediction,
    Vehicle,
    BatchResult,
    HealthStatus,
    RiskLevel,
} from 'vehk-axle';

Telemetry API​

Send Single Telemetry​

const response = await client.telemetry.send({
    vehicle_id: 'TRUCK-001',
    sensor_data: {
        speed: 65,
        rpm: 2500,
        coolant_temp: 92,
        fuel_level: 45,
        battery_voltage: 12.6
    },
    timestamp: '2026-01-14T10:00:00Z',  // Optional
    location: { lat: 12.97, lng: 77.59 }  // Optional
});

console.log(response.telemetry_id);

Send Batch Telemetry​

const result = await client.telemetry.sendBatch([
    { vehicle_id: 'TRUCK-001', sensor_data: { speed: 65, rpm: 2500 } },
    { vehicle_id: 'TRUCK-002', sensor_data: { speed: 70, rpm: 2800 } },
    { vehicle_id: 'TRUCK-003', sensor_data: { speed: 55, rpm: 2200 } },
]);

console.log(`Processed: ${result.records_processed}`);
console.log(`Time: ${result.processing_time_ms}ms`);

Tracking API​

Uses POST /api/external/track, batch /api/external/track/batch, GET /api/external/devices/locations, GET /api/external/devices/:id/location. device_id must be a registered device (ID or IMEI).

Send one point​

await client.tracking.send({
    device_id: '862061048760001',
    latitude: 12.9716,
    longitude: 77.5946,
    speed: 45.2,
    heading: 90,
    timestamp: '2026-03-26T10:00:00Z',
    ignition: true,
    battery_voltage: 12.6,
    satellites: 8,
    event: 'periodic',
    extra: { vendor: 'acme' },
});

Batch (up to 100)​

await client.tracking.sendBatch([
    { device_id: 'dev-1', latitude: 12.97, longitude: 77.59, speed: 45 },
    { device_id: 'dev-2', latitude: 13.01, longitude: 77.61, speed: 30 },
]);

Locations​

const fleet: DeviceLocation[] = await client.tracking.locations();
const latest: DeviceLocation = await client.tracking.location('862061048760001');

Predictions API​

Get Prediction​

const prediction = await client.predictions.get('TRUCK-001', {
    speed: 65,
    rpm: 2500,
    coolant_temp: 92
});

console.log(`Health Score: ${prediction.health_score}%`);
console.log(`Status: ${prediction.health_status}`);
console.log(`Risk: ${prediction.risk_level}`);

// Get maintenance alerts
prediction.maintenance_alerts.forEach(alert => {
    console.log(`- ${alert.type}: ${alert.description}`);
});

// Get recommendations
prediction.recommendations.forEach(rec => {
    console.log(`💡 ${rec}`);
});

List Recent Predictions​

// Get all recent predictions
const predictions = await client.predictions.list();

// Filter by vehicle
const vehiclePredictions = await client.predictions.list('TRUCK-001', 10);

predictions.forEach(p => {
    console.log(`${p.vehicle_id}: ${p.health_score}%`);
});

Vehicles API​

List All Vehicles​

const vehicles = await client.vehicles.list();

vehicles.forEach(vehicle => {
    console.log(`${vehicle.vehicle_id}: ${vehicle.make} ${vehicle.model}`);
    console.log(`  Health Score: ${vehicle.health_score}%`);
});

Devices API​

const all = await client.devices.list();
const activeOnly = await client.devices.list('active');

Error handling​

import { VehkClient } from 'vehk-axle';

const client = new VehkClient('vehk_your_key');

try {
    const prediction = await client.predictions.get('VH-001', { speed: 65 });
    console.log(prediction.health_score);
} catch (error) {
    if (error.message.includes('[401]')) {
        console.error('❌ Invalid API key');
    } else if (error.message.includes('[429]')) {
        console.error('⏳ Rate limited');
    } else if (error.message.includes('[503]')) {
        console.error('🔌 Service unavailable');
    } else {
        console.error('⚠️ Error:', error.message);
    }
}

Errors are thrown as Error with "[status] message" (via Axios). Expect 401 (auth), 403 (subscription, scope, or predict quota), 429 (rate limit). Production External API requires an active/trialing subscription; prediction calls may hit token quotas.

TypeScript interfaces​

TelemetryData​

interface TelemetryData {
    vehicle_id: string;
    sensor_data: Record<string, any>;
    timestamp?: string;
    location?: { lat: number; lng: number };
}

TrackingData / DeviceLocation​

interface TrackingData {
    device_id: string;
    latitude: number;
    longitude: number;
    speed?: number;
    heading?: number;
    altitude?: number;
    timestamp?: string;
    ignition?: boolean;
    battery_voltage?: number;
    satellites?: number;
    event?: string;
    extra?: Record<string, any>;
}

interface DeviceLocation {
    device_id: string;
    unique_id?: string;
    vehicle_id?: string;
    latitude: number;
    longitude: number;
    speed?: number;
    heading?: number;
    ignition?: boolean;
    battery_voltage?: number;
    timestamp?: string;
    halt_status?: boolean;
    idling_status?: boolean;
    is_overspeed?: boolean;
}

Prediction​

interface Prediction {
    vehicle_id: string;
    health_score: number;
    health_status: 'critical' | 'warning' | 'healthy' | 'unknown';
    risk_level: 'high' | 'medium' | 'low' | 'none';
    components: Record<string, ComponentHealth>;
    maintenance_alerts: MaintenanceAlert[];
    recommendations: string[];
    confidence: number;
    metadata: {
        model_version: string;
        processing_time_ms: number;
        timestamp: string;
    };
}

Vehicle​

interface Vehicle {
    id: string;
    vehicle_id: string;
    vin?: string;
    make?: string;
    model?: string;
    year?: number;
    registration?: string;
    health_score?: number;
}

Browser usage​

The SDK works in browsers with bundlers like Webpack or Vite:

// React example
import { VehkClient } from 'vehk-axle';

function FleetDashboard() {
    const [vehicles, setVehicles] = useState([]);
    
    useEffect(() => {
        const client = new VehkClient(process.env.REACT_APP_VEHK_API_KEY);
        client.vehicles.list().then(setVehicles);
    }, []);
    
    return (
        <div>
            {vehicles.map(v => (
                <div key={v.id}>
                    {v.vehicle_id}: {v.health_score}%
                </div>
            ))}
        </div>
    );
}

Node.js backend example​

import express from 'express';
import { VehkClient } from 'vehk-axle';

const app = express();
const vehk = new VehkClient(process.env.VEHK_API_KEY!);

app.post('/api/telemetry', async (req, res) => {
    const { vehicle_id, sensor_data } = req.body;
    
    // Forward to Vehk
    const result = await vehk.telemetry.send({
        vehicle_id,
        sensor_data
    });
    
    res.json(result);
});

app.get('/api/predictions/:vehicleId', async (req, res) => {
    const prediction = await vehk.predictions.get(
        req.params.vehicleId,
        req.body.sensor_data
    );
    
    res.json({
        health_score: prediction.health_score,
        status: prediction.health_status,
        recommendations: prediction.recommendations
    });
});

app.listen(3000);

Health check​

// Check if API is reachable
const health = await client.healthCheck();
console.log(`API Status: ${health.status}`);

Supported sensor fields​

FieldDescriptionUnit
speedVehicle speedkm/h
rpmEngine RPMRPM
coolant_tempCoolant temperature°C
fuel_levelFuel level%
battery_voltageBattery voltageV
oil_pressureOil pressurePSI
throttleThrottle position%
intake_air_tempIntake air temperature°C
ambient_tempAmbient temperature°C
odometerOdometer readingkm