@bisondesk/core-sdk 1.0.681 → 1.0.683

package/src/utils/mileage.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'vitest';
+import { Categories } from '../constants.js';
+import { ContractMileage, MileageStatus, MileageTrendDirection } from '../types/mileage.js';
+import {
+  getMileageAlert,
+  getMileageStatus,
+  getMileageSummary,
+  getMileageTrend,
+} from './mileage.js';
+
+const now = new Date('2026-09-30T12:00:00Z');
+const lastReadingAt = '2026-09-30T06:00:00Z';
+
+describe('getMileageStatus', () => {
+  test.each([
+    { name: 'silent for more than three days', lastReadingAt: '2026-09-26T09:00:00Z' },
+    { name: 'that never reported', lastReadingAt: undefined },
+  ])('a device $name has no signal, whatever its last figures say', ({ lastReadingAt }) => {
+    expect(
+      getMileageStatus({ category: Categories.Van, last30DaysKm: 8_950, lastReadingAt }, now),
+    ).toBe(MileageStatus.NoSignal);
+  });
+
+  test('a device quiet for three days still has a signal', () => {
+    expect(
+      getMileageStatus(
+        { category: Categories.Van, last30DaysKm: 3_000, lastReadingAt: '2026-09-27T09:00:00Z' },
+        now,
+      ),
+    ).toBe(MileageStatus.Normal);
+  });
+
+  test('a device installed less than 30 days ago is too early to judge', () => {
+    expect(
+      getMileageStatus(
+        { last30DaysKm: 40, lastReadingAt, trackedSince: '2026-09-15T08:00:00Z' },
+        now,
+      ),
+    ).toBe(MileageStatus.TooEarly);
+  });
+
+  test.each([
+    { category: Categories.Van, last30DaysKm: 249, expected: MileageStatus.Low },
+    { category: Categories.Van, last30DaysKm: 250, expected: MileageStatus.Normal },
+    { category: Categories.Van, last30DaysKm: 7_500, expected: MileageStatus.Normal },
+    { category: Categories.Van, last30DaysKm: 7_501, expected: MileageStatus.High },
+    { category: Categories.Car, last30DaysKm: 7_501, expected: MileageStatus.High },
+    { category: Categories.TractorHead, last30DaysKm: 12_000, expected: MileageStatus.Normal },
+    { category: Categories.TractorHead, last30DaysKm: 12_001, expected: MileageStatus.High },
+    { category: Categories.Truck, last30DaysKm: 12_001, expected: MileageStatus.High },
+    { category: Categories.Machine, last30DaysKm: 50_000, expected: MileageStatus.Normal },
+    { category: undefined, last30DaysKm: 50_000, expected: MileageStatus.Normal },
+  ])('$category at $last30DaysKm km is $expected', ({ category, last30DaysKm, expected }) => {
+    expect(
+      getMileageStatus(
+        { category, last30DaysKm, lastReadingAt, trackedSince: '2025-01-01T00:00:00Z' },
+        now,
+      ),
+    ).toBe(expected);
+  });
+});
+
+describe('getMileageAlert', () => {
+  test.each([
+    MileageStatus.Low,
+    MileageStatus.High,
+    MileageStatus.NoSignal,
+  ])('%s on an overdue contract is an alert', (status) => {
+    expect(getMileageAlert(status, true)).toBe(status);
+  });
+
+  test.each([MileageStatus.Normal, MileageStatus.TooEarly])('%s is never an alert', (status) => {
+    expect(getMileageAlert(status, true)).toBeUndefined();
+  });
+
+  test('a contract without overdue invoices has no alert', () => {
+    expect(getMileageAlert(MileageStatus.Low, false)).toBeUndefined();
+  });
+});
+
+describe('getMileageTrend', () => {
+  test('has no trend without a yearly average', () => {
+    expect(getMileageTrend(1_000, undefined)).toBeUndefined();
+    expect(getMileageTrend(1_000, 0)).toBeUndefined();
+  });
+
+  test.each([
+    { last30DaysKm: 13_200, direction: MileageTrendDirection.Up, percent: 32 },
+    { last30DaysKm: 11_500, direction: MileageTrendDirection.Up, percent: 15 },
+    { last30DaysKm: 11_400, direction: MileageTrendDirection.Flat, percent: 14 },
+    { last30DaysKm: 8_600, direction: MileageTrendDirection.Flat, percent: -14 },
+    { last30DaysKm: 8_500, direction: MileageTrendDirection.Down, percent: -15 },
+    { last30DaysKm: 300, direction: MileageTrendDirection.Down, percent: -97 },
+  ])('$last30DaysKm km against 10 000 is $direction $percent%', ({
+    last30DaysKm,
+    direction,
+    percent,
+  }) => {
+    expect(getMileageTrend(last30DaysKm, 10_000)).toEqual({ direction, percent });
+  });
+});
+
+describe('getMileageSummary', () => {
+  const vehicle = (
+    contractId: string,
+    status: MileageStatus,
+    alert: ContractMileage['alert'],
+    last30DaysKm: number,
+    yearAvg30DaysKm?: number,
+  ): ContractMileage => ({ contractId, status, alert, last30DaysKm, yearAvg30DaysKm });
+
+  test('counts flagged vehicles per alert and leaves silent devices out of the km', () => {
+    expect(
+      getMileageSummary([
+        vehicle('a', MileageStatus.NoSignal, MileageStatus.NoSignal, 9_000, 9_000),
+        vehicle('b', MileageStatus.NoSignal, undefined, 4_000),
+        vehicle('c', MileageStatus.High, MileageStatus.High, 13_000, 10_000),
+        vehicle('d', MileageStatus.Low, MileageStatus.Low, 100, 2_000),
+        vehicle('e', MileageStatus.Low, undefined, 200),
+        vehicle('f', MileageStatus.TooEarly, undefined, 1_500),
+      ]),
+    ).toEqual({
+      vehicles: 6,
+      noSignal: 1,
+      high: 1,
+      low: 1,
+      issues: 3,
+      last30DaysKm: 14_800,
+      trend: { direction: MileageTrendDirection.Flat, percent: 9 },
+    });
+  });
+
+  test('has no km and no trend when no device is reporting', () => {
+    const summary = getMileageSummary([
+      vehicle('a', MileageStatus.NoSignal, MileageStatus.NoSignal, 9_000, 9_000),
+    ]);
+
+    expect(summary.last30DaysKm).toBeUndefined();
+    expect(summary.trend).toBeUndefined();
+  });
+
+  test('is all zeros for a dossier without tracked vehicles', () => {
+    expect(getMileageSummary([])).toEqual({
+      vehicles: 0,
+      noSignal: 0,
+      high: 0,
+      low: 0,
+      issues: 0,
+    });
+  });
+});

package/src/utils/mileage.ts

@@ -0,0 +1,111 @@
+import { differenceInCalendarDays, parseISO } from 'date-fns';
+import { sumBy } from 'lodash-es';
+import { Categories } from '../constants.js';
+import {
+  ContractMileage,
+  MileageAlert,
+  MileageStatus,
+  MileageSummary,
+  MileageTrend,
+  MileageTrendDirection,
+} from '../types/mileage.js';
+
+export const MILEAGE_LOW_KM_30_DAYS = 250;
+export const MILEAGE_TREND_BAND = 0.15;
+export const KM_FILTER_MAX = 15_000;
+export const KM_FILTER_STEP = 250;
+
+const MILEAGE_WINDOW_DAYS = 30;
+const MILEAGE_SIGNAL_LOST_AFTER_DAYS = 3;
+
+export const MILEAGE_HIGH_KM_30_DAYS: { [category: string]: number } = {
+  [Categories.Van]: 7_500,
+  [Categories.Car]: 7_500,
+  [Categories.TractorHead]: 12_000,
+  [Categories.Truck]: 12_000,
+};
+
+/**
+ * A device that has not reported for more than three days, or never did, has no signal: its km
+ * figures stop refreshing, so they say nothing about how much the vehicle drives.
+ */
+export const getMileageStatus = (
+  input: { category?: string; last30DaysKm: number; lastReadingAt?: string; trackedSince?: string },
+  now: Date = new Date(),
+): MileageStatus => {
+  if (
+    input.lastReadingAt == null ||
+    differenceInCalendarDays(now, parseISO(input.lastReadingAt)) > MILEAGE_SIGNAL_LOST_AFTER_DAYS
+  ) {
+    return MileageStatus.NoSignal;
+  }
+  if (
+    input.trackedSince != null &&
+    differenceInCalendarDays(now, parseISO(input.trackedSince)) < MILEAGE_WINDOW_DAYS
+  ) {
+    return MileageStatus.TooEarly;
+  }
+  if (input.last30DaysKm < MILEAGE_LOW_KM_30_DAYS) {
+    return MileageStatus.Low;
+  }
+  const highLimit = input.category != null ? MILEAGE_HIGH_KM_30_DAYS[input.category] : undefined;
+  if (highLimit != null && input.last30DaysKm > highLimit) {
+    return MileageStatus.High;
+  }
+  return MileageStatus.Normal;
+};
+
+const isOutsideLimits = (status: MileageStatus): status is MileageAlert =>
+  status === MileageStatus.Low ||
+  status === MileageStatus.High ||
+  status === MileageStatus.NoSignal;
+
+/** Debt follow-up only cares about mileage outside the limits on a contract that is overdue. */
+export const getMileageAlert = (
+  status: MileageStatus,
+  overdue: boolean,
+): MileageAlert | undefined => (overdue && isOutsideLimits(status) ? status : undefined);
+
+export const getMileageTrend = (
+  last30DaysKm: number,
+  yearAvg30DaysKm: number | undefined,
+): MileageTrend | undefined => {
+  if (yearAvg30DaysKm == null || yearAvg30DaysKm === 0) {
+    return undefined;
+  }
+  const change = (last30DaysKm - yearAvg30DaysKm) / yearAvg30DaysKm;
+  const percent = Math.round(change * 100);
+  if (change >= MILEAGE_TREND_BAND) {
+    return { direction: MileageTrendDirection.Up, percent };
+  }
+  if (change <= -MILEAGE_TREND_BAND) {
+    return { direction: MileageTrendDirection.Down, percent };
+  }
+  return { direction: MileageTrendDirection.Flat, percent };
+};
+
+/**
+ * Counts a dossier's flagged vehicles and adds up the km of the ones still reporting. A silent
+ * device's figures stay frozen at its last reading, so they are left out of the total and the trend.
+ */
+export const getMileageSummary = (mileage: ContractMileage[]): MileageSummary => {
+  const countAlert = (alert: MileageAlert) => mileage.filter((item) => item.alert === alert).length;
+  const noSignal = countAlert(MileageStatus.NoSignal);
+  const high = countAlert(MileageStatus.High);
+  const low = countAlert(MileageStatus.Low);
+  const reporting = mileage.filter((item) => item.status !== MileageStatus.NoSignal);
+  const withAverage = reporting.filter((item) => item.yearAvg30DaysKm != null);
+
+  return {
+    vehicles: mileage.length,
+    noSignal,
+    high,
+    low,
+    issues: noSignal + high + low,
+    last30DaysKm: reporting.length > 0 ? sumBy(reporting, (item) => item.last30DaysKm) : undefined,
+    trend: getMileageTrend(
+      sumBy(withAverage, (item) => item.last30DaysKm),
+      sumBy(withAverage, (item) => item.yearAvg30DaysKm ?? 0),
+    ),
+  };
+};