@fleetkeep/cli 0.1.2 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Fleetkeep CLI
 
-The Fleetkeep CLI gives an operator or software agent the same bounded fleet import path as the
-Fleetkeep dashboard. It can list vehicles, preview CSV or XLSX imports and apply the exact
-previewed file.
+The Fleetkeep CLI gives an operator or software agent the complete published Fleetkeep vehicle API.
+It can list, inspect, add, update and delete vehicles, bulk-add registrations, preview CSV or XLSX
+imports and apply the exact previewed file.
 
 ## Safety model
 
@@ -11,6 +11,8 @@ previewed file.
 - Every apply request has an idempotency key. Retrying the same request does not duplicate vehicles
   or equipment history.
 - Existing vehicle dates and current equipment are not overwritten by spreadsheet import.
+- Vehicle deletion requires the exact vehicle ID as an explicit confirmation value.
+- Updates distinguish omitted fields from fields explicitly cleared with `--clear`.
 - Interactive login uses an OAuth 2.1 public client with S256 PKCE and a loopback callback.
 - Stored access and refresh tokens use an owner-only local file and are never accepted as command
   arguments.
@@ -24,10 +26,17 @@ Node.js 20 or newer is required. Sign in through Fleetkeep in your browser, then
 ```sh
 fleetkeep auth login
 fleetkeep vehicles list
+fleetkeep vehicles get <vehicle-id> --json
+fleetkeep vehicles add "AB12 CDE" --label "Service van" --operational-status active --json
+fleetkeep vehicles update <vehicle-id> --operational-status off_road --status-notes "Unsafe tyre"
+fleetkeep vehicles update <vehicle-id> --clear assignedDriverName,assignedDriverContact
+fleetkeep vehicles bulk-add "AB12 CDE" "XY34 ZZZ" --json
+fleetkeep vehicles delete <vehicle-id> --confirm <vehicle-id>
 fleetkeep import preview vehicles.xlsx
 fleetkeep import apply vehicles.xlsx --confirm <digest-from-preview>
 ```
 
-Use `--json` for machine-readable output. Set `FLEETKEEP_API_URL` to an alternate origin for local
-or staging verification. For unattended automation, set `FLEETKEEP_ACCESS_TOKEN` in the process
-environment instead of storing or passing a token in command arguments.
+Run `fleetkeep --help` for every supported vehicle field. Use `--json` for machine-readable output.
+Set `FLEETKEEP_API_URL` to an alternate origin for local or staging verification. For unattended
+automation, set `FLEETKEEP_ACCESS_TOKEN` in the process environment instead of storing or passing a
+token in command arguments.

package/fleetkeep.mjs

@@ -14,9 +14,29 @@ Usage:
   fleetkeep auth status
   fleetkeep auth logout
   fleetkeep vehicles list [--json]
+  fleetkeep vehicles get <vehicle-id> [--json]
+  fleetkeep vehicles add <registration> [vehicle options] [--json]
+  fleetkeep vehicles update <vehicle-id> [vehicle options] [--clear <field,...>] [--json]
+  fleetkeep vehicles delete <vehicle-id> --confirm <vehicle-id> [--json]
+  fleetkeep vehicles bulk-add <registration>... [--json]
   fleetkeep import preview <file.csv|file.xlsx> [--json]
   fleetkeep import apply <file.csv|file.xlsx> --confirm <digest> [--idempotency-key <key>] [--json]
 
+Vehicle options:
+  --label <text>
+  --insurance-due-date <YYYY-MM-DD>
+  --last-service-date <YYYY-MM-DD>
+  --last-service-mileage <integer>
+  --service-interval-months <integer>
+  --operational-status <active|standby|in_maintenance|off_road|sold_or_removed>
+  --assigned-driver-name <text>
+  --assigned-driver-contact <text>
+  --status-notes <text>
+
+Clearable update fields:
+  label, insuranceDueDate, lastServiceDate, lastServiceMileage, serviceIntervalMonths,
+  assignedDriverName, assignedDriverContact, statusNotes
+
 Environment:
   FLEETKEEP_ACCESS_TOKEN  Optional OAuth token override for automation
   FLEETKEEP_API_URL       API origin (default: https://fleetkeep.co.uk)
@@ -37,6 +57,104 @@ function option(args, name) {
   return value && !value.startsWith('--') ? value : '';
 }
 
+function requiredValue(args, name) {
+  const value = option(args, name);
+  if (value === '') throw new Error(`${name} requires a value.`);
+  return value;
+}
+
+const VEHICLE_OPTIONS = new Map([
+  ['--label', { field: 'label', type: 'string' }],
+  ['--insurance-due-date', { field: 'insuranceDueDate', type: 'date' }],
+  ['--last-service-date', { field: 'lastServiceDate', type: 'date' }],
+  [
+    '--last-service-mileage',
+    { field: 'lastServiceMileage', type: 'integer', min: 0, max: 1500000 }
+  ],
+  [
+    '--service-interval-months',
+    { field: 'serviceIntervalMonths', type: 'integer', min: 1, max: 120 }
+  ],
+  ['--operational-status', { field: 'operationalStatus', type: 'status' }],
+  ['--assigned-driver-name', { field: 'assignedDriverName', type: 'string' }],
+  ['--assigned-driver-contact', { field: 'assignedDriverContact', type: 'string' }],
+  ['--status-notes', { field: 'statusNotes', type: 'string' }]
+]);
+
+const CLEARABLE_FIELDS = new Set(
+  [...VEHICLE_OPTIONS.values()]
+    .map(({ field }) => field)
+    .filter((field) => field !== 'operationalStatus')
+);
+const OPERATIONAL_STATUSES = new Set([
+  'active',
+  'standby',
+  'in_maintenance',
+  'off_road',
+  'sold_or_removed'
+]);
+
+function parseVehicleValue(name, value, config) {
+  if (config.type === 'string') return value;
+  if (config.type === 'date') {
+    const date = new Date(`${value}T00:00:00Z`);
+    if (
+      !/^\d{4}-\d{2}-\d{2}$/.test(value) ||
+      Number.isNaN(date.getTime()) ||
+      date.toISOString().slice(0, 10) !== value
+    ) {
+      throw new Error(`${name} must be a valid date in YYYY-MM-DD format.`);
+    }
+    return value;
+  }
+  if (config.type === 'status') {
+    if (!OPERATIONAL_STATUSES.has(value)) {
+      throw new Error(`${name} must be one of: ${[...OPERATIONAL_STATUSES].join(', ')}.`);
+    }
+    return value;
+  }
+  if (!/^-?\d+$/.test(value)) throw new Error(`${name} must be an integer.`);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < config.min || number > config.max) {
+    throw new Error(`${name} must be between ${config.min} and ${config.max}.`);
+  }
+  return number;
+}
+
+function vehicleBody(args, { allowClear = false } = {}) {
+  const body = {};
+  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 (allowClear) {
+    recognised.add('--clear');
+    const clear = requiredValue(args, '--clear');
+    if (clear !== null) {
+      for (const field of clear
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean)) {
+        if (!CLEARABLE_FIELDS.has(field)) {
+          throw new Error(`--clear contains an unknown or non-clearable field: ${field}.`);
+        }
+        if (Object.hasOwn(body, field)) {
+          throw new Error(`${field} cannot be set and cleared in the same request.`);
+        }
+        body[field] = null;
+      }
+    }
+  }
+
+  for (const arg of args) {
+    if (arg.startsWith('--') && !recognised.has(arg)) throw new Error(`Unknown option: ${arg}.`);
+  }
+  return body;
+}
+
 function apiOrigin() {
   const value = (process.env.FLEETKEEP_API_URL || DEFAULT_API_URL).trim().replace(/\/$/, '');
   let url;
@@ -62,7 +180,10 @@ async function request(path, { method = 'GET', body }) {
     },
     ...(body ? { body: JSON.stringify(body) } : {})
   });
-  const payload = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+  const payload =
+    response.status === 204
+      ? null
+      : await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
   if (!response.ok) {
     const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${response.status}`;
     throw new Error(`Fleetkeep API rejected the request (${response.status}): ${code}`);
@@ -70,6 +191,15 @@ async function request(path, { method = 'GET', body }) {
   return payload;
 }
 
+function vehiclePath(id) {
+  if (!id || id.startsWith('--')) throw new Error('A vehicle ID is required.');
+  return `/api/v1/vehicles/${encodeURIComponent(id)}`;
+}
+
+function printJsonOr(payload, jsonOutput, line) {
+  process.stdout.write(jsonOutput ? `${JSON.stringify(payload, null, 2)}\n` : `${line}\n`);
+}
+
 async function spreadsheetPayload(fileArg) {
   if (!fileArg || fileArg.startsWith('--')) throw new Error('A .csv or .xlsx file is required.');
   const path = resolve(fileArg);
@@ -163,6 +293,70 @@ async function main() {
     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`);
+    else {
+      const vehicle = payload.vehicle;
+      process.stdout.write(
+        `${vehicle.registration}\t${vehicle.label || ''}\t${vehicle.make || ''}\t${vehicle.operationalStatus || ''}\n`
+      );
+    }
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'add') {
+    const registration = args[2];
+    if (!registration || registration.startsWith('--'))
+      throw new Error('A registration is required.');
+    const body = { registration, ...vehicleBody(args.slice(3)) };
+    const payload = await request('/api/v1/vehicles', { method: 'POST', body });
+    printJsonOr(payload, jsonOutput, `Vehicle added: ${registration} (${payload.id})`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'update') {
+    const body = vehicleBody(args.slice(3), { allowClear: true });
+    if (Object.keys(body).length === 0) {
+      throw new Error('Update requires at least one vehicle option or --clear field.');
+    }
+    const payload = await request(vehiclePath(args[2]), { method: 'PATCH', body });
+    printJsonOr(payload, jsonOutput, `Vehicle updated: ${args[2]}`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'delete') {
+    const id = args[2];
+    const confirmId = option(args, '--confirm');
+    if (!id || id.startsWith('--')) throw new Error('A vehicle ID is required.');
+    if (confirmId !== id) {
+      throw new Error('Delete is blocked until --confirm exactly matches the vehicle ID.');
+    }
+    await request(vehiclePath(id), { method: 'DELETE' });
+    printJsonOr({ ok: true, deletedVehicleId: id }, jsonOutput, `Vehicle deleted: ${id}`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'bulk-add') {
+    const registrations = args.slice(2).filter((arg) => arg !== '--json');
+    if (registrations.length === 0) throw new Error('At least one registration is required.');
+    if (registrations.length > 50) throw new Error('Bulk add accepts at most 50 registrations.');
+    const payload = await request('/api/v1/vehicles/bulk', {
+      method: 'POST',
+      body: { registrations }
+    });
+    if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    else {
+      for (const vehicle of payload.created || []) {
+        process.stdout.write(`Added: ${vehicle.registration} (${vehicle.id})\n`);
+      }
+      for (const error of payload.errors || []) {
+        process.stdout.write(`Not added: ${error.reg} (${error.reason})\n`);
+      }
+    }
+    return;
+  }
+
   if (args[0] === 'import' && args[1] === 'preview') {
     const body = await spreadsheetPayload(args[2]);
     const payload = await request('/api/v1/imports/vehicles/preview', {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.1.2",
-  "description": "Preview and apply Fleetkeep fleet spreadsheet imports through the Fleetkeep API",
+  "version": "0.2.0",
+  "description": "Manage Fleetkeep vehicles and guarded fleet spreadsheet imports through the Fleetkeep API",
   "type": "module",
   "bin": {
     "fleetkeep": "fleetkeep.mjs"