@fleetkeep/cli 0.6.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:
@@ -41,6 +62,18 @@ 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:
 
@@ -115,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
 ```
@@ -128,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/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]
@@ -260,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);
@@ -325,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']) {
@@ -398,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

@@ -92,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',
@@ -104,7 +125,7 @@ const definitions = [
     'POST',
     '/api/v1/vehicles/{id}/service-records',
     'maintenance:write',
-    { idempotency: true }
+    { confirmation: true, idempotency: true }
   ],
   [
     'getServiceRecord',
@@ -225,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.6.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();
+  }
+}