@bisondesk/core-sdk 1.0.682 → 1.0.683

package/src/types/leasing-search.ts

@@ -2,6 +2,7 @@ import { InsuranceEntry } from '@bisondesk/commons-sdk/insurance';
 import { Contact, Organization } from './crm.js';
 import { PublicSearchDefinition } from './definitions.js';
 import { LeasingContract } from './leasing.js';
+import { ContractMileage } from './mileage.js';
 import { Vehicle } from './vehicles.js';
 
 export type LeasingPublicSearchDefinitions = {
@@ -27,6 +28,7 @@ export type SearchLeasingContract = {
     supplierName?: string;
     hasActiveRecurrence?: boolean;
     lastRecurrenceRunAt?: string;
+    mileage?: ContractMileage;
   };
 };
 

package/src/types/mileage.ts

@@ -0,0 +1,51 @@
+export enum MileageStatus {
+  NoSignal = 'no-signal',
+  TooEarly = 'too-early',
+  Low = 'low',
+  Normal = 'normal',
+  High = 'high',
+}
+
+export type MileageAlert = MileageStatus.Low | MileageStatus.High | MileageStatus.NoSignal;
+
+export enum MileageTrendDirection {
+  Up = 'up',
+  Down = 'down',
+  Flat = 'flat',
+}
+
+export type MileageTrend = {
+  direction: MileageTrendDirection;
+  /** The last 30 days against the 12-month average, in percent. */
+  percent: number;
+};
+
+/** Km driven by a contract's vehicle, read from its wired track-and-trace device. */
+export type ContractMileage = {
+  contractId: string;
+  stockNumber?: string;
+  status: MileageStatus;
+  /** The status, when it is outside the limits and the contract has overdue invoices. */
+  alert?: MileageAlert;
+  last30DaysKm: number;
+  /** Absent while the device document predates the yearly figures: unknown, not zero. */
+  currentYearKm?: number;
+  /** Km per 30 days over the past 12 months; absent under 60 tracked days. */
+  yearAvg30DaysKm?: number;
+  trend?: MileageTrend;
+  lastReadingAt?: string;
+};
+
+/** A debtor dossier's tracked vehicles at a glance, for the dossier lists and boards. */
+export type MileageSummary = {
+  vehicles: number;
+  /** Vehicles flagged per alert: outside the limits on a contract with overdue invoices. */
+  noSignal: number;
+  high: number;
+  low: number;
+  issues: number;
+  /** Km over the last 30 days of the vehicles still reporting; absent when none is. */
+  last30DaysKm?: number;
+  /** Those vehicles' km against their combined 12-month average. */
+  trend?: MileageTrend;
+};

package/src/types/vehicle-purchase-payments.ts

@@ -105,10 +105,9 @@ export type VehiclePurchasePaymentBff = {
 };
 
 /**
- * The group an unpaid purchase falls in, in the order the Unpaid list ranks them: sold to a client
- * (whether or not it has arrived), arrived on our park and not sold, or still expected — neither
- * sold nor arrived. The single Unpaid list filters by `sold` and `logisticStatus` instead; the
- * `group` filter and `meta.counts` serve the client that paged each group on its own.
+ * The group an unpaid purchase is listed under, in the order the Unpaid list shows them: sold to a
+ * client (whether or not it has arrived), arrived on our park and not sold, or still expected —
+ * neither sold nor arrived.
  */
 export enum UnpaidPurchaseGroup {
   Sold = 'sold',
@@ -116,34 +115,6 @@ export enum UnpaidPurchaseGroup {
   Expected = 'expected',
 }
 
-/**
- * Where the vehicle behind an unpaid purchase stands, in the order the Unpaid list ranks its sales:
- * delivered to the client, arrived on our park, or still expected from the supplier. Delivered comes
- * from the sale side, so only a sold vehicle is delivered, whether or not it passed our park.
- */
-export enum UnpaidPurchaseLogisticStatus {
-  Delivered = 'delivered',
-  Arrived = 'arrived',
-  Expected = 'expected',
-}
-
-/** The filters on the Unpaid list. A filter left out keeps every purchase. */
-export type UnpaidPurchasesFilters = {
-  /**
-   * Free text, case-insensitive: every word must appear in the stock number, VIN, vehicle title or
-   * supplier name.
-   */
-  q?: string;
-  sold?: boolean;
-  logisticStatus?: UnpaidPurchaseLogisticStatus;
-  /** Purchasers (`purchase.purchasedBy`); a purchase matches any of them. */
-  purchasedBy?: string[];
-  branchId?: string;
-  /** The vehicle's condition (`external.condition.used`); a vehicle without one matches neither. */
-  used?: boolean;
-  group?: UnpaidPurchaseGroup;
-};
-
 /**
  * A row on the Unpaid tab: an agreed purchase that still has an amount to authorise for payment.
  * Derived from the purchase deal and the payments already authorised, not a payment record.
@@ -166,13 +137,11 @@ export type UnpaidPurchase = {
   supplierName?: string;
 };
 
-/** What a page of the Unpaid list carries besides its rows. */
+/** What a page of one Unpaid group carries besides its rows. */
 export type UnpaidPurchasesMeta = {
   /** Whether the requester may authorise a payment, as on the vehicle purchase tab. */
   canAllowPayment: boolean;
-  /** Everyone who purchased an unpaid purchase, unfiltered, for the purchaser filter. */
-  purchasers: string[];
-  /** How many purchases each group holds, unfiltered. */
+  /** How many purchases each group holds, for the group headers. */
   counts: Record<UnpaidPurchaseGroup, number>;
 };
 

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),
+    ),
+  };
+};