@fleetkeep/cli 0.4.0 → 0.6.0

package/README.md

@@ -5,6 +5,73 @@ API. Friendly commands cover common vehicle and spreadsheet work. The allowliste
 command covers equipment, maintenance, defects, walkarounds, files, reminders, contacts, bookings,
 tolls, tracking, guidance and exports without opening arbitrary or unpublished paths.
 
+## Shared jobs and running costs
+
+Friendly commands return JSON, including missing-data and stale-tracking fields:
+
+```sh
+fleetkeep costs list --from 2026-09-01 --to 2026-09-30
+fleetkeep costs record --data-file expense.json
+fleetkeep drivers activity --search JOB-42
+fleetkeep tracking list
+fleetkeep tracking route <vehicle-id> --period 7d
+```
+
+Driver activity returns up to 100 journeys and 100 inspections from the company's
+central record. Search filters journeys by job reference, driver or registration;
+inspections remain the latest 100. The activity endpoint must be deployed before
+using this command. Route history requires a supported connected tracker.
+Expense files use the fields below; keep the same UUID and body when retrying.
+
+`fleetkeep jobs list --search JOB-42` finds company jobs. Use
+`fleetkeep jobs save JOB-42 --title "Depot installation"` to create or update a reference,
+and `fleetkeep jobs close <job-id>` or `reopen <job-id>` to change its availability.
+Closing a job preserves its journey history. These owner operations need an active Fleet plan.
+
+`fleetkeep api call getRunningCosts --query from=2026-09-01 --query to=2026-09-30`
+returns recorded GBP costs and missing-data flags. `recordFleetExpense` accepts a JSON body
+with `id` (UUID), `vehicleId`, `incurredOn`, `category`, `amount` (GBP decimal string) and
+`description`. Reuse the UUID and identical body on retries. Dates span up to one year.
+Supported categories are fuel, insurance, repair, parking and other. Negative amounts record
+refunds or corrections. Service costs and recorded GBP tolls are included separately, so do
+not enter them again. Account JSON exports include jobs, journeys and additional costs.
+
+Xero authorisation and bill review take place in the web portal. Saved SHVL grants and
+credentials are not transferred between products or customer workspaces.
+
+## Service intervals and equipment
+
+Set one service interval in days, weeks or months. The vehicle command clears the
+alternative unit when switching, and converts weeks to days:
+
+```sh
+fleetkeep vehicles update <vehicle-id> --service-interval-weeks 6
+fleetkeep vehicles update <vehicle-id> --service-interval-months 12
+fleetkeep vehicles update <vehicle-id> --clear serviceIntervalDays,serviceIntervalMonths
+fleetkeep api call getWalkaroundSummary
+fleetkeep api call listVehicleEquipment --path id=<vehicle-id>
+fleetkeep api call updateVehicleEquipment --path id=<vehicle-id> --data-file equipment.json
+```
+
+The walkaround summary returns vehicles checked today in London time, not a
+roadworthiness certificate. Equipment payloads support `presetKey`, provider,
+reference, cover dates, reminders and up to eight `details` label/value pairs.
+Use an `Arrangement` detail for the confirmed ownership type, such as `Hired`.
+Omitting details preserves existing values; an empty array explicitly clears them.
+Use `previewEquipmentTemplate` before `applyEquipmentTemplate` for fleet-wide setup.
+
+With the matching API update deployed, `createMaintenance` also accepts
+`forecastConsent: true` and a `forecast` object containing `baselineDate`,
+`baselineMileage`, `intervalMiles`, `annualMileage` and `reminderDays` (0 means on
+the estimated date). Supply the actual last check, not an assumed MOT check date.
+Duplicate setup does not create another reminder; refresh the maintenance list.
+`completeMaintenance` accepts `completedDate` and `completedMileage` for
+an existing forecast. Supply the identical body for preview and confirmation;
+the next cycle retains the saved mileage interval and reminder timing. Ordinary
+maintenance updates cannot edit calculated forecast dates. There are no automatic
+fuel-card feeds in the CLI. Wex credentials and Xero authorisation are entered in
+the website, never through CLI command arguments.
+
 ## Safety model
 
 - `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.

package/api-command.mjs

@@ -97,6 +97,9 @@ function operationPath(operation, assignments) {
     if (!values.has(name) || values.get(name) === '') {
       throw new Error(`${operation.id} requires --path ${name}=<value>.`);
     }
+    if (values.get(name) === '.' || values.get(name) === '..') {
+      throw new Error(`--path ${name} must not be a dot segment.`);
+    }
     path = path.replace(`{${name}}`, encodeURIComponent(values.get(name)));
   }
   return path;
@@ -280,9 +283,9 @@ export async function runApiCommand(args) {
     throw new Error('Use `fleetkeep api operations` or `fleetkeep api call`.');
   const operationId = args[1];
   if (!operationId || operationId.startsWith('--')) throw new Error('An operation ID is required.');
-  const operation = operations[operationId];
-  if (!operation) {
+  if (!Object.hasOwn(operations, operationId)) {
     throw new Error(`Unknown or unpublished Fleetkeep operation: ${operationId}.`);
   }
+  const operation = operations[operationId];
   await callOperation(operation, args.slice(2));
 }

package/fleetkeep.mjs

@@ -21,9 +21,18 @@ Usage:
   fleetkeep vehicles delete <vehicle-id> [--confirmation <server-token>] [--json]
   fleetkeep vehicles bulk-add <registration>... [--json]
   fleetkeep drivers list [--json]
+  fleetkeep drivers activity [--search <job-driver-registration>] [--json]
+  fleetkeep costs list [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--json]
+  fleetkeep costs record --data-file <expense.json>
+  fleetkeep tracking list [--json]
+  fleetkeep tracking route <vehicle-id> [--period <period>] [--json]
   fleetkeep drivers invite <email> --name <name> [--json]
   fleetkeep drivers resend <driver-id> [--json]
   fleetkeep drivers revoke <driver-id> [--json]
+  fleetkeep jobs list [--search <reference>] [--json]
+  fleetkeep jobs save <reference> --title <title> [--json]
+  fleetkeep jobs close <job-id> [--json]
+  fleetkeep jobs reopen <job-id> [--json]
   fleetkeep import preview <file.csv|file.xlsx> [--json]
   fleetkeep import apply <file.csv|file.xlsx> --confirm <digest> [--idempotency-key <key>] [--json]
   fleetkeep api operations [--json]
@@ -47,6 +56,8 @@ Vehicle options:
   --last-service-date <YYYY-MM-DD>
   --last-service-mileage <integer>
   --service-interval-months <integer>
+  --service-interval-days <integer>
+  --service-interval-weeks <integer>
   --operational-status <active|standby|in_maintenance|off_road|sold_or_removed>
   --assigned-driver-name <text>
   --assigned-driver-contact <text>
@@ -54,7 +65,10 @@ Vehicle options:
 
 Clearable update fields:
   label, insuranceDueDate, lastServiceDate, lastServiceMileage, serviceIntervalMonths,
-  assignedDriverName, assignedDriverContact, statusNotes
+  serviceIntervalDays, assignedDriverName, assignedDriverContact, statusNotes
+
+Choose one service interval unit. Weeks are stored as days. Setting an interval
+clears the alternative unit so an old interval cannot override the new one.
 
 Environment:
   FLEETKEEP_ACCESS_TOKEN  Optional OAuth token override for automation
@@ -103,6 +117,11 @@ const VEHICLE_OPTIONS = new Map([
     '--service-interval-months',
     { field: 'serviceIntervalMonths', type: 'integer', min: 1, max: 120 }
   ],
+  ['--service-interval-days', { field: 'serviceIntervalDays', type: 'integer', min: 1, max: 3650 }],
+  [
+    '--service-interval-weeks',
+    { field: 'serviceIntervalDays', type: 'integer', min: 1, max: 521, multiplier: 7 }
+  ],
   ['--operational-status', { field: 'operationalStatus', type: 'status' }],
   ['--assigned-driver-name', { field: 'assignedDriverName', type: 'string' }],
   ['--assigned-driver-contact', { field: 'assignedDriverContact', type: 'string' }],
@@ -151,11 +170,22 @@ function parseVehicleValue(name, value, config) {
 
 function vehicleBody(args, { allowClear = false } = {}) {
   const body = {};
+  const intervalOptions = [
+    '--service-interval-days',
+    '--service-interval-weeks',
+    '--service-interval-months'
+  ];
+  if (intervalOptions.filter((name) => args.includes(name)).length > 1) {
+    throw new Error('Choose one service interval unit: days, weeks or months.');
+  }
   const recognised = new Set(['--json']);
   for (const [name, config] of VEHICLE_OPTIONS) {
     recognised.add(name);
     const value = requiredValue(args, name);
-    if (value !== null) body[config.field] = parseVehicleValue(name, value, config);
+    if (value !== null) {
+      const parsed = parseVehicleValue(name, value, config);
+      body[config.field] = config.multiplier ? parsed * config.multiplier : parsed;
+    }
   }
 
   if (allowClear) {
@@ -180,6 +210,8 @@ function vehicleBody(args, { allowClear = false } = {}) {
   for (const arg of args) {
     if (arg.startsWith('--') && !recognised.has(arg)) throw new Error(`Unknown option: ${arg}.`);
   }
+  if (body.serviceIntervalDays != null) body.serviceIntervalMonths = null;
+  if (body.serviceIntervalMonths != null) body.serviceIntervalDays = null;
   return body;
 }
 
@@ -293,6 +325,46 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'costs' && args[1] === 'list') {
+    const query = [];
+    for (const name of ['from', 'to']) {
+      const value = option(args, `--${name}`);
+      if (value) query.push('--query', `${name}=${value}`);
+    }
+    await runApiCommand(['call', 'getRunningCosts', ...query]);
+    return;
+  }
+  if (args[0] === 'costs' && args[1] === 'record') {
+    const file = option(args, '--data-file');
+    if (!file) throw new Error('--data-file is required. Reuse the expense UUID on retries.');
+    await runApiCommand(['call', 'recordFleetExpense', '--data-file', file]);
+    return;
+  }
+  if (args[0] === 'tracking' && args[1] === 'list') {
+    await runApiCommand(['call', 'listTrackingSnapshots']);
+    return;
+  }
+  if (args[0] === 'tracking' && args[1] === 'route') {
+    if (!args[2] || args[2].startsWith('--')) throw new Error('A vehicle ID is required.');
+    const period = option(args, '--period');
+    await runApiCommand([
+      'call',
+      'getWexRouteHistory',
+      '--path',
+      `vehicleId=${args[2]}`,
+      ...(period ? ['--query', `period=${period}`] : [])
+    ]);
+    return;
+  }
+  if (args[0] === 'drivers' && args[1] === 'activity') {
+    const payload = await request(
+      `/api/v1/drivers/activity?q=${encodeURIComponent(option(args, '--search') || '')}`,
+      {}
+    );
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
   if (args[0] === 'auth' && args[1] === 'login') {
     await login({ noBrowser: args.includes('--no-browser') });
     return;
@@ -409,6 +481,30 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'jobs' && ['list', 'save', 'close', 'reopen'].includes(args[1])) {
+    const action = args[1];
+    let payload;
+    if (action === 'list') {
+      payload = await request(
+        `/api/v1/jobs?q=${encodeURIComponent(option(args, '--search') || '')}`,
+        {}
+      );
+    } else {
+      if (!args[2] || args[2].startsWith('--'))
+        throw new Error('A job reference or ID is required.');
+      if (action === 'save' && !option(args, '--title')) throw new Error('--title is required.');
+      payload = await request('/api/v1/jobs', {
+        method: 'POST',
+        body:
+          action === 'save'
+            ? { action: 'save', reference: args[2], title: option(args, '--title') }
+            : { action: 'status', id: args[2], status: action === 'close' ? 'closed' : 'active' }
+      });
+    }
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
   if (args[0] === 'drivers' && args[1] === 'list') {
     const payload = await request('/api/v1/drivers', {});
     if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/operations.mjs

@@ -1,5 +1,17 @@
 /** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
 const definitions = [
+  ['importProviderJobs', 'POST', '/api/v1/jobs/import', 'operations:write'],
+  ['listFleetJobs', 'GET', '/api/v1/jobs', 'operations:read', { query: ['q'] }],
+  ['saveFleetJob', 'POST', '/api/v1/jobs', 'operations:write'],
+  ['getRunningCosts', 'GET', '/api/v1/costs', 'operations:read', { query: ['from', 'to'] }],
+  ['recordFleetExpense', 'POST', '/api/v1/costs', 'operations:write'],
+  [
+    'listDriverJobs',
+    'GET',
+    '/api/v1/driver-workspace/{id}/jobs',
+    'operations:read',
+    { query: ['q'] }
+  ],
   ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
   ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
   ['getVehicle', 'GET', '/api/v1/vehicles/{id}', 'vehicles:read'],
@@ -22,6 +34,7 @@ const definitions = [
   ['previewVehicleImport', 'POST', '/api/v1/imports/vehicles/preview', 'vehicles:read'],
   ['applyVehicleImport', 'POST', '/api/v1/imports/vehicles/apply', 'vehicles:write'],
   ['getWalkaroundDefinition', 'GET', '/api/v1/operations/walkaround-definition', 'operations:read'],
+  ['getWalkaroundSummary', 'GET', '/api/v1/operations/walkaround-summary', 'operations:read'],
   [
     'listWalkarounds',
     'GET',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {