@fleetkeep/cli 0.5.0 → 0.7.0

package/README.md

@@ -5,6 +5,27 @@ 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.
 
+## Start here
+
+Run `npx @fleetkeep/cli setup` after installation. It signs you in through your
+browser, checks your existing account and shows the next step. Return to the
+terminal after each website step and refresh to see the current status.
+
+Choose your intended fleet size on the website. Eligible new accounts can start
+a 30-day trial without a card; the price is shown before confirmation. Existing
+customers keep their account and subscription. App-store subscribers should
+contact Fleetkeep about Fleet access before purchasing a separate web plan.
+
+Once Fleet access is active, use `fleetkeep import preview "fleet.xlsx"` to
+review a spreadsheet before saving. The preview supplies the exact confirmation
+command. Review missing dates, reminder timing and recipients on the dashboard.
+Add a card only through the website after checking the first payment date.
+
+`fleetkeep setup --json` returns the current setup state for automation without
+opening a browser or starting an interactive login. `--no-browser` prints links
+for you to open yourself. Setup never starts a subscription, imports records or
+enables reminders on its own. It requires the matching setup API deployment.
+
 ## Shared jobs and running costs
 
 Friendly commands return JSON, including missing-data and stale-tracking fields:
@@ -39,6 +60,51 @@ not enter them again. Account JSON exports include jobs, journeys and additional
 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
+
+Record completed servicing by registration without looking up an internal vehicle ID first:
+
+```sh
+fleetkeep service record "BD15 KFG" --date 2026-09-27 --mileage 48212 \
+  --work "Scheduled service"
+```
+
+Fleetkeep matches the exact normalised registration and shows the proposed record. Nothing is
+saved until the operator repeats the same command with the short-lived confirmation token. The
+CLI derives a stable idempotency key from the matched vehicle and record, so an identical retry
+returns the original result rather than creating a duplicate.
+
+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.
@@ -82,6 +148,9 @@ fleetkeep api call listTrackingSnapshots
 fleetkeep api call getWexRouteHistory --path vehicleId=<vehicle-id> --query period=7d
 fleetkeep api call createServiceRecord --path id=<vehicle-id> \
   --idempotency-key <unique-value> --data-file service-record.json
+fleetkeep api call createServiceRecord --path id=<vehicle-id> \
+  --idempotency-key <same-unique-value> --confirmation <server-token> \
+  --data-file service-record.json
 fleetkeep api call uploadVehiclePhoto --path id=<vehicle-id> --file photo=van.jpg
 fleetkeep api call downloadFleetSpreadsheet --output fleetkeep-export.xlsx
 ```
@@ -95,3 +164,7 @@ Set `FLEETKEEP_API_URL` to an alternate origin for local or staging verification
 automation, set `FLEETKEEP_ACCESS_TOKEN` in the process environment. OAuth access and refresh tokens
 are never accepted in command arguments. Short-lived action confirmations are supplied separately
 with `--confirmation`.
+
+Service-record creation is a two-step operator-confirmed action. The first call returns a 409
+challenge. Retry the identical body and idempotency key with its `--confirmation` token. A safe
+retry with the same key returns the original record instead of creating a duplicate.

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/auth.mjs

@@ -224,7 +224,7 @@ export async function getAccessToken() {
 }
 
 /** @param {string} url */
-function openBrowser(url) {
+export function openBrowser(url) {
   /** @type {[string, string[]]} */
   const command =
     process.platform === 'darwin'

package/fleetkeep.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { basename, extname, resolve } from 'node:path';
 import { runApiCommand } from './api-command.mjs';
+import { runSetup } from './setup.mjs';
 import { authStatus, getAccessToken, login, logout } from './auth.mjs';
 
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
@@ -11,6 +13,7 @@ function usage() {
   return `Fleetkeep CLI
 
 Usage:
+  fleetkeep setup [--no-browser] [--json]
   fleetkeep auth login [--no-browser]
   fleetkeep auth status
   fleetkeep auth logout
@@ -20,6 +23,8 @@ Usage:
   fleetkeep vehicles update <vehicle-id> [vehicle options] [--clear <field,...>] [--json]
   fleetkeep vehicles delete <vehicle-id> [--confirmation <server-token>] [--json]
   fleetkeep vehicles bulk-add <registration>... [--json]
+  fleetkeep service record <registration> --date <YYYY-MM-DD> --mileage <integer> --work <text>
+    [--supplier <text>] [--invoice <text>] [--confirmation <server-token>] [--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]
@@ -56,6 +61,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>
@@ -63,7 +70,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
@@ -112,6 +122,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' }],
@@ -160,11 +175,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) {
@@ -189,6 +215,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;
 }
 
@@ -237,6 +265,129 @@ function printJsonOr(payload, jsonOutput, line) {
   process.stdout.write(jsonOutput ? `${JSON.stringify(payload, null, 2)}\n` : `${line}\n`);
 }
 
+function normaliseRegistration(value) {
+  return value.toUpperCase().replace(/\s+/g, '');
+}
+
+function serviceRecordBody(args) {
+  const allowed = new Set([
+    '--date',
+    '--mileage',
+    '--work',
+    '--supplier',
+    '--invoice',
+    '--notes',
+    '--next-date',
+    '--next-mileage',
+    '--confirmation',
+    '--json'
+  ]);
+  for (const arg of args) {
+    if (arg.startsWith('--') && !allowed.has(arg)) throw new Error(`Unknown option: ${arg}.`);
+  }
+  const servicedAt = option(args, '--date');
+  const mileage = option(args, '--mileage');
+  const workSummary = option(args, '--work');
+  if (!servicedAt) throw new Error('--date is required.');
+  parseVehicleValue('--date', servicedAt, { type: 'date' });
+  if (!mileage) throw new Error('--mileage is required.');
+  const odometerMileage = parseVehicleValue('--mileage', mileage, {
+    type: 'integer',
+    min: 0,
+    max: 1500000
+  });
+  if (!workSummary) throw new Error('--work is required.');
+  const body = { servicedAt, odometerMileage, workSummary };
+  for (const [name, field] of [
+    ['--supplier', 'supplier'],
+    ['--invoice', 'invoiceReference'],
+    ['--notes', 'notes'],
+    ['--next-date', 'nextServiceDueDate']
+  ]) {
+    const value = option(args, name);
+    if (value) {
+      if (name === '--next-date') parseVehicleValue(name, value, { type: 'date' });
+      body[field] = value;
+    }
+  }
+  const nextMileage = option(args, '--next-mileage');
+  if (nextMileage) {
+    body.nextServiceDueMileage = parseVehicleValue('--next-mileage', nextMileage, {
+      type: 'integer',
+      min: 0,
+      max: 1500000
+    });
+  }
+  return body;
+}
+
+async function recordServiceByRegistration(registration, args, jsonOutput) {
+  if (!registration || registration.startsWith('--'))
+    throw new Error('A registration is required.');
+  const body = serviceRecordBody(args);
+  const listed = await request('/api/v1/vehicles', {});
+  const wanted = normaliseRegistration(registration);
+  const matches = (listed.vehicles || []).filter(
+    (vehicle) => normaliseRegistration(vehicle.registration || '') === wanted
+  );
+  if (matches.length === 0) throw new Error(`No vehicle matched registration ${registration}.`);
+  if (matches.length > 1)
+    throw new Error(`More than one vehicle matched registration ${registration}.`);
+  const vehicle = matches[0];
+  const idempotencyKey = `service:${createHash('sha256')
+    .update(JSON.stringify({ vehicleId: vehicle.id, body }))
+    .digest('hex')
+    .slice(0, 32)}`;
+  const confirmation = option(args, '--confirmation');
+  try {
+    const payload = await request(
+      `/api/v1/vehicles/${encodeURIComponent(vehicle.id)}/service-records`,
+      {
+        method: 'POST',
+        body,
+        headers: {
+          'idempotency-key': idempotencyKey,
+          ...(confirmation ? { 'x-fleetkeep-confirmation': confirmation } : {})
+        }
+      }
+    );
+    printJsonOr(
+      payload,
+      jsonOutput,
+      `${payload.replay ? 'Service record already saved' : 'Service record saved'}: ${vehicle.registration}, ${body.servicedAt}, ${body.odometerMileage.toLocaleString('en-GB')} miles.`
+    );
+  } catch (error) {
+    if (
+      error instanceof FleetkeepApiError &&
+      error.status === 409 &&
+      error.payload?.error === 'confirmation_required' &&
+      typeof error.payload.confirmationToken === 'string'
+    ) {
+      if (jsonOutput)
+        process.stdout.write(
+          `${JSON.stringify({ ...error.payload, vehicle, proposedRecord: body }, null, 2)}\n`
+        );
+      else {
+        process.stdout.write(
+          [
+            'No record was saved.',
+            `Vehicle: ${vehicle.registration}${vehicle.label ? ` (${vehicle.label})` : ''}`,
+            `Service date: ${body.servicedAt}`,
+            `Mileage: ${body.odometerMileage.toLocaleString('en-GB')}`,
+            `Work: ${body.workSummary}`,
+            '',
+            'After checking those details, repeat the same command with:',
+            `--confirmation ${error.payload.confirmationToken}`
+          ].join('\n') + '\n'
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+}
+
 async function spreadsheetPayload(fileArg) {
   if (!fileArg || fileArg.startsWith('--')) throw new Error('A .csv or .xlsx file is required.');
   const path = resolve(fileArg);
@@ -302,6 +453,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'setup') {
+    await runSetup(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'costs' && args[1] === 'list') {
     const query = [];
     for (const name of ['from', 'to']) {
@@ -375,6 +531,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'service' && args[1] === 'record') {
+    await recordServiceByRegistration(args[2], args.slice(3), jsonOutput);
+    return;
+  }
+
   if (args[0] === 'vehicles' && args[1] === 'get') {
     const payload = await request(vehiclePath(args[2]), {});
     if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/operations.mjs

@@ -34,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',
@@ -91,6 +92,27 @@ const definitions = [
     'vehicles:write',
     { confirmation: true }
   ],
+  [
+    'listServiceSchedules',
+    'GET',
+    '/api/v1/vehicles/{id}/service-schedules',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'listServiceEvidenceRequests',
+    'GET',
+    '/api/v1/vehicles/{id}/service-evidence-requests',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'getServiceEvidenceTimeline',
+    'GET',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/contacts',
+    'maintenance:read',
+    { query: ['limit'] }
+  ],
   [
     'listServiceRecords',
     'GET',
@@ -103,7 +125,7 @@ const definitions = [
     'POST',
     '/api/v1/vehicles/{id}/service-records',
     'maintenance:write',
-    { idempotency: true }
+    { confirmation: true, idempotency: true }
   ],
   [
     'getServiceRecord',
@@ -224,6 +246,7 @@ const definitions = [
     'operations:read',
     { query: ['period'] }
   ],
+  ['getSetupStatus', 'GET', '/api/v1/setup', 'profile:read'],
   ['getProfile', 'GET', '/api/v1/profile', 'profile:read'],
   ['getDriverGuidance', 'GET', '/api/v1/driver-guidance', 'guidance:read'],
   [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "auth.mjs",
     "fleetkeep.mjs",
     "operations.mjs",
+    "setup.mjs",
     "README.md"
   ],
   "engines": {

package/setup.mjs

@@ -0,0 +1,94 @@
+import { createInterface } from 'node:readline/promises';
+import { getAccessToken, loadStoredTokens, login, oauthConfig, openBrowser } from './auth.mjs';
+
+/** @param {string[]} args */
+export async function runSetup(args) {
+  for (const arg of args) {
+    if (!['--json', '--no-browser'].includes(arg)) throw new Error(`Unknown setup option: ${arg}`);
+  }
+  const json = args.includes('--json');
+  const interactive = !json && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const origin = oauthConfig().origin;
+  if (!process.env.FLEETKEEP_ACCESS_TOKEN?.trim() && !(await loadStoredTokens())) {
+    if (!interactive) {
+      const next = { nextStep: 'sign_in', command: 'fleetkeep auth login', url: `${origin}/login` };
+      process.stdout.write(
+        json
+          ? `${JSON.stringify(next)}\n`
+          : `Sign in or create your Fleetkeep account in the browser:\n${next.command}\nThen run fleetkeep setup again.\n`
+      );
+      return;
+    }
+    process.stdout.write(
+      'Sign in or create your account in the browser. Existing plans stay on the same account.\n'
+    );
+    await login({ noBrowser: args.includes('--no-browser') });
+  }
+  const input = interactive
+    ? createInterface({ input: process.stdin, output: process.stdout })
+    : null;
+  try {
+    do {
+      const response = await fetch(new URL('/api/v1/setup', origin), {
+        headers: { authorization: `Bearer ${await getAccessToken()}`, accept: 'application/json' },
+        redirect: 'error',
+        signal: AbortSignal.timeout(25_000)
+      });
+      if (!response.ok)
+        throw new Error(
+          `Setup status unavailable (${response.status}). No changes were made. Try fleetkeep auth login if your session expired.`
+        );
+      const state = await response.json();
+      if (json) {
+        process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+        return;
+      }
+      process.stdout.write(
+        `\nFleetkeep setup\n${Number(state.vehicleCount).toLocaleString('en-GB')} vehicles saved\n${state.nextAction}\n`
+      );
+      if (state.billing.trialEndsAt)
+        process.stdout.write(
+          `Trial ends: ${new Date(state.billing.trialEndsAt).toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'Europe/London' })}\n`
+        );
+      process.stdout.write(`${state.paymentNote}\n`);
+      const steps = /** @type {Record<string, string>} */ ({
+        plan: 'plans',
+        fleet_access: 'billing',
+        vehicles: 'addVehicle',
+        reminders: 'reminders',
+        review: 'dashboard'
+      });
+      const key = steps[state.nextStep];
+      // Only open the known website paths, never an arbitrary returned URL.
+      const paths = /** @type {Record<string, string>} */ ({
+        plans: '/dashboard/choose-plan',
+        billing: '/dashboard/settings#billing',
+        addVehicle: '/dashboard/vehicles/new',
+        reminders: '/dashboard/settings#reminders',
+        dashboard: '/dashboard'
+      });
+      const url = new URL(paths[key] || '/dashboard', origin).href;
+      process.stdout.write(`Next: ${url}\n`);
+      if (state.canUseApi)
+        process.stdout.write(
+          'Spreadsheet: fleetkeep import preview "fleet.xlsx"\nReview the preview, then use its confirmation command to save.\n'
+        );
+      if (!input) return;
+      const answer = (
+        await input.question(
+          '\n[o] Open next step  [r] Refresh after completing it  [Enter] Finish: '
+        )
+      )
+        .trim()
+        .toLowerCase();
+      if (answer === 'o') {
+        if (!args.includes('--no-browser')) openBrowser(url);
+        await input.question(
+          'Complete the step in your browser, then press Enter to check again. '
+        );
+      } else if (answer !== 'r') return;
+    } while (true);
+  } finally {
+    input?.close();
+  }
+}