@bisondesk/core-sdk 1.0.682 → 1.0.684

package/lib/utils/mileage.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'vitest';
+import { Categories } from '../constants.js';
+import { 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, status, alert, last30DaysKm, yearAvg30DaysKm) => ({ 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,
+        });
+    });
+});
+//# sourceMappingURL=mileage.test.js.map

package/lib/utils/mileage.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mileage.test.js","sourceRoot":"/","sources":["utils/mileage.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAmB,aAAa,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,sBAAsB,CAAC,CAAC;AAC7C,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAE7C,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,IAAI,CAAC,IAAI,CAAC;QACR,EAAE,IAAI,EAAE,iCAAiC,EAAE,aAAa,EAAE,sBAAsB,EAAE;QAClF,EAAE,IAAI,EAAE,qBAAqB,EAAE,aAAa,EAAE,SAAS,EAAE;KAC1D,CAAC,CAAC,6DAA6D,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE;QACtF,MAAM,CACJ,gBAAgB,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,GAAG,CAAC,CACxF,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,CACJ,gBAAgB,CACd,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,EACxF,GAAG,CACJ,CACF,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gEAAgE,EAAE,GAAG,EAAE;QAC1E,MAAM,CACJ,gBAAgB,CACd,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,EACzE,GAAG,CACJ,CACF,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC;QACR,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE;QAC5E,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE;QAC/E,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE;QACjF,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE;QAC/E,EAAE,QAAQ,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE;QAC/E,EAAE,QAAQ,EAAE,UAAU,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE;QAC1F,EAAE,QAAQ,EAAE,UAAU,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE;QACxF,EAAE,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE;QAClF,EAAE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE;QACtF,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE;KAC9E,CAAC,CAAC,4CAA4C,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,EAAE;QACxF,MAAM,CACJ,gBAAgB,CACd,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,EAC/E,GAAG,CACJ,CACF,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,IAAI,CAAC,IAAI,CAAC;QACR,aAAa,CAAC,GAAG;QACjB,aAAa,CAAC,IAAI;QAClB,aAAa,CAAC,QAAQ;KACvB,CAAC,CAAC,uCAAuC,EAAE,CAAC,MAAM,EAAE,EAAE;QACrD,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,EAAE;QAC3F,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,CAAC,eAAe,CAAC,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QAC1D,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC;QACR,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1E,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1E,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC5E,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE;QAC5E,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE;QAC5E,EAAE,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE;KAC3E,CAAC,CAAC,yDAAyD,EAAE,CAAC,EAC7D,YAAY,EACZ,SAAS,EACT,OAAO,GACR,EAAE,EAAE;QACH,MAAM,CAAC,eAAe,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,MAAM,OAAO,GAAG,CACd,UAAkB,EAClB,MAAqB,EACrB,KAA+B,EAC/B,YAAoB,EACpB,eAAwB,EACP,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC,CAAC;IAErF,IAAI,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACrF,MAAM,CACJ,iBAAiB,CAAC;YAChB,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;YAC1E,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC;YACtD,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;YACpE,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,GAAG,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC;YAC9D,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC;YAC/C,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC;SACvD,CAAC,CACH,CAAC,OAAO,CAAC;YACR,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,CAAC;YACX,IAAI,EAAE,CAAC;YACP,GAAG,EAAE,CAAC;YACN,MAAM,EAAE,CAAC;YACT,YAAY,EAAE,MAAM;YACpB,KAAK,EAAE,EAAE,SAAS,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;SAC7D,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC9D,MAAM,OAAO,GAAG,iBAAiB,CAAC;YAChC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;SAC3E,CAAC,CAAC;QAEH,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,aAAa,EAAE,CAAC;QAC7C,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,aAAa,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACpC,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,CAAC;YACX,IAAI,EAAE,CAAC;YACP,GAAG,EAAE,CAAC;YACN,MAAM,EAAE,CAAC;SACV,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { describe, expect, test } from 'vitest';\nimport { Categories } from '../constants.js';\nimport { ContractMileage, MileageStatus, MileageTrendDirection } from '../types/mileage.js';\nimport {\n  getMileageAlert,\n  getMileageStatus,\n  getMileageSummary,\n  getMileageTrend,\n} from './mileage.js';\n\nconst now = new Date('2026-09-30T12:00:00Z');\nconst lastReadingAt = '2026-09-30T06:00:00Z';\n\ndescribe('getMileageStatus', () => {\n  test.each([\n    { name: 'silent for more than three days', lastReadingAt: '2026-09-26T09:00:00Z' },\n    { name: 'that never reported', lastReadingAt: undefined },\n  ])('a device $name has no signal, whatever its last figures say', ({ lastReadingAt }) => {\n    expect(\n      getMileageStatus({ category: Categories.Van, last30DaysKm: 8_950, lastReadingAt }, now),\n    ).toBe(MileageStatus.NoSignal);\n  });\n\n  test('a device quiet for three days still has a signal', () => {\n    expect(\n      getMileageStatus(\n        { category: Categories.Van, last30DaysKm: 3_000, lastReadingAt: '2026-09-27T09:00:00Z' },\n        now,\n      ),\n    ).toBe(MileageStatus.Normal);\n  });\n\n  test('a device installed less than 30 days ago is too early to judge', () => {\n    expect(\n      getMileageStatus(\n        { last30DaysKm: 40, lastReadingAt, trackedSince: '2026-09-15T08:00:00Z' },\n        now,\n      ),\n    ).toBe(MileageStatus.TooEarly);\n  });\n\n  test.each([\n    { category: Categories.Van, last30DaysKm: 249, expected: MileageStatus.Low },\n    { category: Categories.Van, last30DaysKm: 250, expected: MileageStatus.Normal },\n    { category: Categories.Van, last30DaysKm: 7_500, expected: MileageStatus.Normal },\n    { category: Categories.Van, last30DaysKm: 7_501, expected: MileageStatus.High },\n    { category: Categories.Car, last30DaysKm: 7_501, expected: MileageStatus.High },\n    { category: Categories.TractorHead, last30DaysKm: 12_000, expected: MileageStatus.Normal },\n    { category: Categories.TractorHead, last30DaysKm: 12_001, expected: MileageStatus.High },\n    { category: Categories.Truck, last30DaysKm: 12_001, expected: MileageStatus.High },\n    { category: Categories.Machine, last30DaysKm: 50_000, expected: MileageStatus.Normal },\n    { category: undefined, last30DaysKm: 50_000, expected: MileageStatus.Normal },\n  ])('$category at $last30DaysKm km is $expected', ({ category, last30DaysKm, expected }) => {\n    expect(\n      getMileageStatus(\n        { category, last30DaysKm, lastReadingAt, trackedSince: '2025-01-01T00:00:00Z' },\n        now,\n      ),\n    ).toBe(expected);\n  });\n});\n\ndescribe('getMileageAlert', () => {\n  test.each([\n    MileageStatus.Low,\n    MileageStatus.High,\n    MileageStatus.NoSignal,\n  ])('%s on an overdue contract is an alert', (status) => {\n    expect(getMileageAlert(status, true)).toBe(status);\n  });\n\n  test.each([MileageStatus.Normal, MileageStatus.TooEarly])('%s is never an alert', (status) => {\n    expect(getMileageAlert(status, true)).toBeUndefined();\n  });\n\n  test('a contract without overdue invoices has no alert', () => {\n    expect(getMileageAlert(MileageStatus.Low, false)).toBeUndefined();\n  });\n});\n\ndescribe('getMileageTrend', () => {\n  test('has no trend without a yearly average', () => {\n    expect(getMileageTrend(1_000, undefined)).toBeUndefined();\n    expect(getMileageTrend(1_000, 0)).toBeUndefined();\n  });\n\n  test.each([\n    { last30DaysKm: 13_200, direction: MileageTrendDirection.Up, percent: 32 },\n    { last30DaysKm: 11_500, direction: MileageTrendDirection.Up, percent: 15 },\n    { last30DaysKm: 11_400, direction: MileageTrendDirection.Flat, percent: 14 },\n    { last30DaysKm: 8_600, direction: MileageTrendDirection.Flat, percent: -14 },\n    { last30DaysKm: 8_500, direction: MileageTrendDirection.Down, percent: -15 },\n    { last30DaysKm: 300, direction: MileageTrendDirection.Down, percent: -97 },\n  ])('$last30DaysKm km against 10 000 is $direction $percent%', ({\n    last30DaysKm,\n    direction,\n    percent,\n  }) => {\n    expect(getMileageTrend(last30DaysKm, 10_000)).toEqual({ direction, percent });\n  });\n});\n\ndescribe('getMileageSummary', () => {\n  const vehicle = (\n    contractId: string,\n    status: MileageStatus,\n    alert: ContractMileage['alert'],\n    last30DaysKm: number,\n    yearAvg30DaysKm?: number,\n  ): ContractMileage => ({ contractId, status, alert, last30DaysKm, yearAvg30DaysKm });\n\n  test('counts flagged vehicles per alert and leaves silent devices out of the km', () => {\n    expect(\n      getMileageSummary([\n        vehicle('a', MileageStatus.NoSignal, MileageStatus.NoSignal, 9_000, 9_000),\n        vehicle('b', MileageStatus.NoSignal, undefined, 4_000),\n        vehicle('c', MileageStatus.High, MileageStatus.High, 13_000, 10_000),\n        vehicle('d', MileageStatus.Low, MileageStatus.Low, 100, 2_000),\n        vehicle('e', MileageStatus.Low, undefined, 200),\n        vehicle('f', MileageStatus.TooEarly, undefined, 1_500),\n      ]),\n    ).toEqual({\n      vehicles: 6,\n      noSignal: 1,\n      high: 1,\n      low: 1,\n      issues: 3,\n      last30DaysKm: 14_800,\n      trend: { direction: MileageTrendDirection.Flat, percent: 9 },\n    });\n  });\n\n  test('has no km and no trend when no device is reporting', () => {\n    const summary = getMileageSummary([\n      vehicle('a', MileageStatus.NoSignal, MileageStatus.NoSignal, 9_000, 9_000),\n    ]);\n\n    expect(summary.last30DaysKm).toBeUndefined();\n    expect(summary.trend).toBeUndefined();\n  });\n\n  test('is all zeros for a dossier without tracked vehicles', () => {\n    expect(getMileageSummary([])).toEqual({\n      vehicles: 0,\n      noSignal: 0,\n      high: 0,\n      low: 0,\n      issues: 0,\n    });\n  });\n});\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bisondesk/core-sdk",
-  "version": "1.0.682",
+  "version": "1.0.684",
   "description": "",
   "type": "module",
   "author": "TheTruckCompany",

package/src/types/crm.ts

@@ -204,6 +204,7 @@ export type SearchOrganization = {
     inUse: boolean; // is this organization in use by any of the branches of this tenant, or is it an organization from another tenant.
     lastActivityAt: string | undefined; // last activity at this organization
     lastActivityBy: string | undefined; // user that did the last activity at this organization
+    contactedBy: string[]; // users who logged any activity tagged with this organization
     engagementTypes: OrgEngagementType[] | undefined; // types of engagements this organization has in the tenant
 
     accountManagers: string[]; // dynamically determined account managers for this organization

package/src/types/leasing-debtors.ts

@@ -2,6 +2,7 @@ import { EmailMessage } from '@bisondesk/commons-sdk/messages';
 import { NextList, PaginatedList } from '@bisondesk/commons-sdk/types';
 import { Contact, Organization } from './crm.js';
 import { LeasingContract } from './leasing.js';
+import { ContractMileage, MileageSummary } from './mileage.js';
 import { BaseSearchRequest, SortFilter, SortOrder } from './search.js';
 import { DataRecord, ReferenceData } from './utils.js';
 
@@ -50,6 +51,9 @@ export type SearchDebtorInfo = {
     riskLevelLabel: string;
     hasActiveContracts: boolean;
   };
+  /** One entry per tracked contract of the organization, copied from the contracts index. */
+  mileage?: ContractMileage[];
+  mileageSummary?: MileageSummary;
 };
 
 export enum DebtorsDossierStatus {
@@ -342,6 +346,9 @@ export type SearchDebtorsDossier = {
     remindersSent: number;
     hasActiveLdrs?: boolean;
   };
+  /** One entry per tracked contract of the organization, copied from the contracts index. */
+  mileage?: ContractMileage[];
+  mileageSummary?: MileageSummary;
 };
 
 /************

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

@@ -102,6 +102,10 @@ export type VehiclePurchasePaymentBff = {
   supplierName?: string;
   /** Export checks on the supplier bank account; filled for the Processing list only. */
   exportChecks?: PaymentExportChecks;
+  /** The documents the vehicle already has, as on the Unpaid list; filled for the Allowed list only. */
+  documents?: UnpaidPurchaseDocument[];
+  /** Due date of the vehicle's latest main purchase invoice; filled for the Allowed list only. */
+  invoiceDueDate?: string;
 };
 
 /**
@@ -117,16 +121,31 @@ export enum UnpaidPurchaseGroup {
 }
 
 /**
- * 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.
+ * Where the vehicle behind an unpaid purchase stands, in the order the Unpaid list ranks them:
+ * delivered to the client, arrived on our park, going straight from the supplier to the client
+ * (`deal.readyToDeliver`), 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',
+  DirectDelivery = 'directDelivery',
   Expected = 'expected',
 }
 
+/**
+ * A document the payments page tracks for the vehicle behind a purchase: the main purchase invoice (a
+ * purchase invoice with a vehicle line, the Purchase Invoice of the vehicle's Document Checks; invoices
+ * for transport or repairs do not count), and the vehicle's registration, the original or a copy. The
+ * registration values are the administrative document types, and only documents filed on the vehicle
+ * count.
+ */
+export enum UnpaidPurchaseDocument {
+  PurchaseInvoice = 'purchase_invoice',
+  Registration = 'registration',
+  RegistrationCopy = 'registration_copy',
+}
+
 /** The filters on the Unpaid list. A filter left out keeps every purchase. */
 export type UnpaidPurchasesFilters = {
   /**
@@ -141,6 +160,8 @@ export type UnpaidPurchasesFilters = {
   branchId?: string;
   /** The vehicle's condition (`external.condition.used`); a vehicle without one matches neither. */
   used?: boolean;
+  /** Documents the vehicle must have, every one of them. */
+  documents?: UnpaidPurchaseDocument[];
   group?: UnpaidPurchaseGroup;
 };
 
@@ -160,8 +181,10 @@ export type UnpaidPurchase = {
   paidAmount: string;
   /** `purchaseAmount − allowedAmount`; always greater than zero for rows shown here. */
   remainingAmount: string;
-  /** Due date of the purchase invoice. */
+  /** Due date of the vehicle's latest main purchase invoice, latest by issue date. */
   invoiceDueDate?: string;
+  /** The documents the vehicle already has. */
+  documents: UnpaidPurchaseDocument[];
   /** Name of the supplier organisation (`vehicle.purchase.organizationId`), resolved for display. */
   supplierName?: string;
 };

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