@fleetkeep/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,23 +1,27 @@
 # Fleetkeep CLI
 
-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.
+The Fleetkeep CLI lets an operator or software agent use every operation in Fleetkeep's published
+API. Friendly commands cover common vehicle and spreadsheet work. The allowlisted `api call`
+command covers equipment, maintenance, defects, walkarounds, files, reminders, contacts, bookings,
+tolls, tracking, guidance and exports without opening arbitrary or unpublished paths.
 
 ## Safety model
 
-- Preview is read-only and uses `vehicles:read`.
-- Apply uses `vehicles:write` and requires the exact SHA-256 digest returned by preview.
-- 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.
+- `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.
+- Consequential actions use short-lived server-issued confirmation tokens. An unconfirmed request
+  returns the token without making the change; review it before repeating with `--confirmation`.
+- Retry-safe creates and sends require `--idempotency-key` when the API contract requires it.
+- Vehicle and toll imports remain preview-first and require the exact preview digest before apply.
+- Multipart uploads accept only explicit `--field` and `--file` values. Each file is capped at 10 MB.
+- Downloads require an explicit output path. Existing files are not replaced unless `--overwrite`
+  is present.
 - 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.
 - `FLEETKEEP_ACCESS_TOKEN` remains available as an explicit environment override for automation.
-- The API retains the import result in Fleetkeep's audit log.
+- OAuth asks only for the published operational scopes. Account deletion, billing, OAuth-client
+  administration and telematics credential operations are not available.
 
 ## Use
 
@@ -31,12 +35,29 @@ fleetkeep vehicles add "AB12 CDE" --label "Service van" --operational-status act
 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 vehicles delete <vehicle-id> --json
+fleetkeep vehicles delete <vehicle-id> --confirmation <server-token> --json
+fleetkeep drivers list
+fleetkeep drivers invite driver@example.com --name "Pat Driver"
+fleetkeep drivers resend <driver-id>
+fleetkeep drivers revoke <driver-id>
 fleetkeep import preview vehicles.xlsx
 fleetkeep import apply vehicles.xlsx --confirm <digest-from-preview>
+fleetkeep api operations --json
+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 uploadVehiclePhoto --path id=<vehicle-id> --file photo=van.jpg
+fleetkeep api call downloadFleetSpreadsheet --output fleetkeep-export.xlsx
 ```
 
-Run `fleetkeep --help` for every supported vehicle field. Use `--json` for machine-readable output.
+Run `fleetkeep --help` for API call options and every supported vehicle field. `api call` returns
+JSON for JSON endpoints and a JSON receipt for saved downloads. Use `--path name=value` for each path
+placeholder, `--query name=value` for query values, and `--data` or `--data-file` for JSON bodies.
+Use repeated `--field` and `--file` options for published multipart operations.
+
 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.
+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`.

package/api-command.mjs

@@ -0,0 +1,288 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+
+import { getAccessToken } from './auth.mjs';
+import { operationList, operations } from './operations.mjs';
+
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+const MAX_JSON_BYTES = 15 * 1024 * 1024;
+
+function apiOrigin() {
+  const value = (process.env.FLEETKEEP_API_URL || 'https://fleetkeep.co.uk')
+    .trim()
+    .replace(/\/$/, '');
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('FLEETKEEP_API_URL must be a valid HTTP or HTTPS origin.');
+  }
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    url.username ||
+    url.password
+  ) {
+    throw new Error('FLEETKEEP_API_URL must be an HTTP or HTTPS origin without a path.');
+  }
+  return url.origin;
+}
+
+function parseAssignment(value, option) {
+  const separator = value.indexOf('=');
+  if (separator < 1) throw new Error(`${option} requires name=value.`);
+  return [value.slice(0, separator), value.slice(separator + 1)];
+}
+
+function parseCallOptions(args) {
+  const parsed = {
+    path: [],
+    query: [],
+    fields: [],
+    files: [],
+    data: null,
+    dataFile: null,
+    confirmation: null,
+    idempotencyKey: null,
+    output: null,
+    overwrite: false,
+    json: false
+  };
+  const repeatable = new Map([
+    ['--path', 'path'],
+    ['--query', 'query'],
+    ['--field', 'fields'],
+    ['--file', 'files']
+  ]);
+  const single = new Map([
+    ['--data', 'data'],
+    ['--data-file', 'dataFile'],
+    ['--confirmation', 'confirmation'],
+    ['--idempotency-key', 'idempotencyKey'],
+    ['--output', 'output']
+  ]);
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--overwrite' || arg === '--json') {
+      parsed[arg === '--overwrite' ? 'overwrite' : 'json'] = true;
+      continue;
+    }
+    const target = repeatable.get(arg) || single.get(arg);
+    if (!target) throw new Error(`Unknown API call option: ${arg}.`);
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
+    if (repeatable.has(arg)) parsed[target].push(parseAssignment(value, arg));
+    else if (parsed[target] !== null) throw new Error(`${arg} may be supplied only once.`);
+    else parsed[target] = value;
+  }
+  return parsed;
+}
+
+function operationPath(operation, assignments) {
+  const values = new Map();
+  for (const [name, value] of assignments) {
+    if (values.has(name)) throw new Error(`--path ${name} was supplied more than once.`);
+    values.set(name, value);
+  }
+  const expected = [...operation.path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+  for (const name of values.keys()) {
+    if (!expected.includes(name))
+      throw new Error(`Unknown path parameter for ${operation.id}: ${name}.`);
+  }
+  let path = operation.path;
+  for (const name of expected) {
+    if (!values.has(name) || values.get(name) === '') {
+      throw new Error(`${operation.id} requires --path ${name}=<value>.`);
+    }
+    path = path.replace(`{${name}}`, encodeURIComponent(values.get(name)));
+  }
+  return path;
+}
+
+function mimeType(path) {
+  return (
+    {
+      '.csv': 'text/csv',
+      '.doc': 'application/msword',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.jpeg': 'image/jpeg',
+      '.jpg': 'image/jpeg',
+      '.mov': 'video/quicktime',
+      '.mp4': 'video/mp4',
+      '.pdf': 'application/pdf',
+      '.png': 'image/png',
+      '.webm': 'video/webm',
+      '.webp': 'image/webp',
+      '.xls': 'application/vnd.ms-excel',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    }[extname(path).toLowerCase()] || 'application/octet-stream'
+  );
+}
+
+async function readBounded(path, maxBytes, label) {
+  const bytes = await readFile(resolve(path));
+  if (bytes.length > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes.`);
+  return bytes;
+}
+
+async function requestBody(operation, options, headers) {
+  const hasMultipart = options.fields.length > 0 || options.files.length > 0;
+  if ((options.data !== null || options.dataFile !== null) && hasMultipart) {
+    throw new Error('--data or --data-file cannot be combined with --field or --file.');
+  }
+  if (options.data !== null && options.dataFile !== null) {
+    throw new Error('--data and --data-file cannot be combined.');
+  }
+  if (hasMultipart && !operation.multipart) {
+    throw new Error(`${operation.id} does not publish a multipart request.`);
+  }
+  if (hasMultipart) {
+    const form = new FormData();
+    for (const [name, value] of options.fields) form.append(name, value);
+    for (const [name, path] of options.files) {
+      const bytes = await readBounded(path, MAX_UPLOAD_BYTES, `Upload ${path}`);
+      form.append(
+        name,
+        new Blob([bytes], { type: mimeType(path) }),
+        resolve(path).split('/').pop()
+      );
+    }
+    return form;
+  }
+  if (options.data === null && options.dataFile === null) return undefined;
+  const source =
+    options.data !== null
+      ? options.data
+      : (await readBounded(options.dataFile, MAX_JSON_BYTES, 'JSON body')).toString('utf8');
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error('The request body must be valid JSON.');
+  }
+  headers.set('content-type', 'application/json');
+  return JSON.stringify(value);
+}
+
+function confirmationResult(payload, operationId) {
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    payload.error === 'confirmation_required' &&
+    typeof payload.confirmationToken === 'string'
+  ) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.stderr.write(
+      `No change was made. Review the action, then repeat ${operationId} with --confirmation <confirmationToken>.\n`
+    );
+    process.exitCode = 2;
+    return true;
+  }
+  return false;
+}
+
+async function writeOutput(path, bytes, overwrite) {
+  const destination = resolve(path);
+  try {
+    await writeFile(destination, bytes, overwrite ? undefined : { flag: 'wx' });
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+      throw new Error(`Output already exists: ${destination}. Use --overwrite to replace it.`, {
+        cause: error
+      });
+    }
+    throw error;
+  }
+  return destination;
+}
+
+async function callOperation(operation, args) {
+  const options = parseCallOptions(args);
+  if (operation.binary && !options.output) {
+    throw new Error(`${operation.id} returns a file and requires --output <path>.`);
+  }
+  if (operation.idempotency && !options.idempotencyKey) {
+    throw new Error(`${operation.id} requires --idempotency-key <unique-value>.`);
+  }
+
+  const url = new URL(operationPath(operation, options.path), apiOrigin());
+  for (const [name, value] of options.query) {
+    if (!operation.query?.includes(name)) {
+      throw new Error(`Unknown query parameter for ${operation.id}: ${name}.`);
+    }
+    url.searchParams.append(name, value);
+  }
+  const headers = new Headers({
+    authorization: `Bearer ${await getAccessToken()}`,
+    accept: 'application/json, application/octet-stream;q=0.9, */*;q=0.8'
+  });
+  if (options.confirmation) headers.set('x-fleetkeep-confirmation', options.confirmation);
+  if (options.idempotencyKey) headers.set('idempotency-key', options.idempotencyKey);
+  const body = await requestBody(operation, options, headers);
+  const response = await fetch(url, {
+    method: operation.method,
+    headers,
+    ...(body ? { body } : {})
+  });
+  const contentType = response.headers.get('content-type') || 'application/octet-stream';
+
+  if (!response.ok) {
+    const payload = contentType.includes('json')
+      ? await response.json().catch(() => null)
+      : { error: (await response.text()).slice(0, 500) || `HTTP ${response.status}` };
+    if (response.status === 409 && confirmationResult(payload, operation.id)) return;
+    const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${response.status}`;
+    throw new Error(`Fleetkeep API rejected ${operation.id} (${response.status}): ${code}`);
+  }
+
+  if (options.output) {
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const destination = await writeOutput(options.output, bytes, options.overwrite);
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, operationId: operation.id, status: response.status, output: destination, bytes: bytes.length, contentType }, null, 2)}\n`
+    );
+    return;
+  }
+  if (response.status === 204) {
+    process.stdout.write(`${JSON.stringify({ ok: true, operationId: operation.id }, null, 2)}\n`);
+    return;
+  }
+  if (!contentType.includes('json')) {
+    throw new Error(`${operation.id} returned ${contentType}; repeat with --output <path>.`);
+  }
+  const payload = await response.json();
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function printOperations(jsonOutput) {
+  if (jsonOutput) {
+    process.stdout.write(`${JSON.stringify({ operations: operationList }, null, 2)}\n`);
+    return;
+  }
+  for (const operation of operationList) {
+    process.stdout.write(
+      `${operation.id}\t${operation.method}\t${operation.path}\t${operation.scope}\n`
+    );
+  }
+}
+
+export async function runApiCommand(args) {
+  if (args[0] === 'operations') {
+    const unknown = args.filter((arg) => arg !== 'operations' && arg !== '--json');
+    if (unknown.length) throw new Error(`Unknown API operations option: ${unknown[0]}.`);
+    printOperations(args.includes('--json'));
+    return;
+  }
+  if (args[0] !== 'call')
+    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) {
+    throw new Error(`Unknown or unpublished Fleetkeep operation: ${operationId}.`);
+  }
+  await callOperation(operation, args.slice(2));
+}

package/auth.mjs

@@ -8,7 +8,24 @@ import { spawn } from 'node:child_process';
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
 const DEFAULT_CLIENT_ID = 'fleetkeep-cli';
 const DEFAULT_REDIRECT_URI = 'http://127.0.0.1:38741/callback';
-const DEFAULT_SCOPES = ['vehicles:read', 'vehicles:write', 'offline_access'];
+export const DEFAULT_SCOPES = [
+  'vehicles:read',
+  'vehicles:write',
+  'operations:read',
+  'operations:write',
+  'tolls:read',
+  'tolls:write',
+  'documents:read',
+  'documents:write',
+  'maintenance:read',
+  'maintenance:write',
+  'reminders:read',
+  'reminders:write',
+  'profile:read',
+  'guidance:read',
+  'exports:read',
+  'offline_access'
+];
 const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
 
 /** @typedef {{ accessToken: string, refreshToken?: string | null, expiresAt: number }} StoredTokens */

package/fleetkeep.mjs

@@ -2,6 +2,7 @@
 
 import { readFile } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
+import { runApiCommand } from './api-command.mjs';
 import { authStatus, getAccessToken, login, logout } from './auth.mjs';
 
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
@@ -17,10 +18,28 @@ Usage:
   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 delete <vehicle-id> [--confirmation <server-token>] [--json]
   fleetkeep vehicles bulk-add <registration>... [--json]
+  fleetkeep drivers list [--json]
+  fleetkeep drivers invite <email> --name <name> [--json]
+  fleetkeep drivers resend <driver-id> [--json]
+  fleetkeep drivers revoke <driver-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]
+  fleetkeep api call <operation-id> [API options]
+
+API options:
+  --path <name=value>          Path parameter; repeat when needed
+  --query <name=value>         Query parameter; repeat when needed
+  --data <json>                JSON request body
+  --data-file <file.json>      JSON request body from a file
+  --field <name=value>         Multipart text field; repeat when needed
+  --file <name=path>           Multipart file; repeat when needed
+  --confirmation <token>       Server-issued action confirmation token
+  --idempotency-key <key>      Required for retry-safe create or send operations
+  --output <path>              Save a download; existing files are protected
+  --overwrite                  Allow --output to replace an existing file
 
 Vehicle options:
   --label <text>
@@ -42,7 +61,16 @@ Environment:
   FLEETKEEP_API_URL       API origin (default: https://fleetkeep.co.uk)
 
 Import is preview-first. Applying requires the exact digest returned by preview.
-Tokens are never accepted as command arguments.`;
+OAuth access and refresh tokens are never accepted as command arguments.`;
+}
+
+class FleetkeepApiError extends Error {
+  constructor(status, payload) {
+    const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${status}`;
+    super(`Fleetkeep API rejected the request (${status}): ${code}`);
+    this.status = status;
+    this.payload = payload;
+  }
 }
 
 function fail(message, exitCode = 1) {
@@ -169,14 +197,15 @@ function apiOrigin() {
   return url.origin;
 }
 
-async function request(path, { method = 'GET', body }) {
+async function request(path, { method = 'GET', body, headers: extraHeaders = {} }) {
   const token = await getAccessToken();
   const response = await fetch(`${apiOrigin()}${path}`, {
     method,
     headers: {
       authorization: `Bearer ${token}`,
       accept: 'application/json',
-      ...(body ? { 'content-type': 'application/json' } : {})
+      ...(body ? { 'content-type': 'application/json' } : {}),
+      ...extraHeaders
     },
     ...(body ? { body: JSON.stringify(body) } : {})
   });
@@ -185,8 +214,7 @@ async function request(path, { method = 'GET', body }) {
       ? 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}`);
+    throw new FleetkeepApiError(response.status, payload);
   }
   return payload;
 }
@@ -280,6 +308,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'api') {
+    await runApiCommand(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'vehicles' && args[1] === 'list') {
     const payload = await request('/api/v1/vehicles', {});
     if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
@@ -327,12 +360,31 @@ async function main() {
 
   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.');
+    const confirmation = option(args, '--confirmation');
+    try {
+      await request(vehiclePath(id), {
+        method: 'DELETE',
+        headers: confirmation ? { 'x-fleetkeep-confirmation': confirmation } : {}
+      });
+    } 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, null, 2)}\n`);
+        else {
+          process.stdout.write(
+            `No vehicle was deleted. Review the vehicle, then repeat with --confirmation ${error.payload.confirmationToken}\n`
+          );
+        }
+        process.exitCode = 2;
+        return;
+      }
+      throw error;
     }
-    await request(vehiclePath(id), { method: 'DELETE' });
     printJsonOr({ ok: true, deletedVehicleId: id }, jsonOutput, `Vehicle deleted: ${id}`);
     return;
   }
@@ -357,6 +409,55 @@ async function main() {
     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`);
+    else {
+      for (const driver of payload.drivers || []) {
+        const state = driver.revokedAt
+          ? 'access removed'
+          : driver.acceptedAt
+            ? 'active'
+            : 'invitation pending';
+        process.stdout.write(`${driver.id}\t${driver.name}\t${driver.email}\t${state}\n`);
+      }
+    }
+    return;
+  }
+
+  if (args[0] === 'drivers' && args[1] === 'invite') {
+    const email = args[2];
+    const name = option(args, '--name');
+    if (!email || email.startsWith('--')) throw new Error('A driver email address is required.');
+    if (!name) throw new Error('--name is required.');
+    const payload = await request('/api/v1/drivers', {
+      method: 'POST',
+      body: { email, name }
+    });
+    printJsonOr(
+      payload,
+      jsonOutput,
+      `Invitation emailed to ${payload.driver.email} (${payload.driver.id})`
+    );
+    return;
+  }
+
+  if (args[0] === 'drivers' && ['resend', 'revoke'].includes(args[1])) {
+    const id = args[2];
+    if (!id || id.startsWith('--')) throw new Error('A driver ID is required.');
+    const action = args[1];
+    const payload = await request(`/api/v1/drivers/${encodeURIComponent(id)}`, {
+      method: 'POST',
+      body: { action }
+    });
+    printJsonOr(
+      payload,
+      jsonOutput,
+      action === 'resend' ? 'Invitation emailed again.' : 'Driver access removed.'
+    );
+    return;
+  }
+
   if (args[0] === 'import' && args[1] === 'preview') {
     const body = await spreadsheetPayload(args[2]);
     const payload = await request('/api/v1/imports/vehicles/preview', {

package/operations.mjs

@@ -0,0 +1,243 @@
+/** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
+const definitions = [
+  ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
+  ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
+  ['getVehicle', 'GET', '/api/v1/vehicles/{id}', 'vehicles:read'],
+  ['updateVehicle', 'PATCH', '/api/v1/vehicles/{id}', 'vehicles:write'],
+  ['deleteVehicle', 'DELETE', '/api/v1/vehicles/{id}', 'vehicles:write', { confirmation: true }],
+  ['listVehicleEquipment', 'GET', '/api/v1/vehicles/{id}/checks', 'vehicles:read'],
+  ['addVehicleEquipment', 'POST', '/api/v1/vehicles/{id}/checks', 'vehicles:write'],
+  ['updateVehicleEquipment', 'PATCH', '/api/v1/vehicles/{id}/checks', 'vehicles:write'],
+  [
+    'removeVehicleEquipment',
+    'DELETE',
+    '/api/v1/vehicles/{id}/checks',
+    'vehicles:write',
+    { confirmation: true }
+  ],
+  ['listEquipmentTemplates', 'GET', '/api/v1/equipment/templates', 'vehicles:read'],
+  ['previewEquipmentTemplate', 'POST', '/api/v1/equipment/templates', 'vehicles:read'],
+  ['applyEquipmentTemplate', 'PUT', '/api/v1/equipment/templates', 'vehicles:write'],
+  ['bulkAddVehicles', 'POST', '/api/v1/vehicles/bulk', 'vehicles:write'],
+  ['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'],
+  [
+    'listWalkarounds',
+    'GET',
+    '/api/v1/vehicles/{id}/walkarounds',
+    'operations:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'submitWalkaround',
+    'POST',
+    '/api/v1/vehicles/{id}/walkarounds',
+    'operations:write',
+    { confirmation: true, multipart: true }
+  ],
+  [
+    'getWalkaroundEvidence',
+    'GET',
+    '/api/v1/vehicles/{id}/walkarounds/{checkId}/media/{mediaId}',
+    'operations:read',
+    { binary: true }
+  ],
+  [
+    'listVehicleDocuments',
+    'GET',
+    '/api/v1/vehicles/{id}/documents',
+    'documents:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'createVehicleDocument',
+    'POST',
+    '/api/v1/vehicles/{id}/documents',
+    'documents:write',
+    { multipart: true }
+  ],
+  [
+    'downloadVehicleDocument',
+    'GET',
+    '/api/v1/vehicles/{id}/documents/{documentId}/download',
+    'documents:read',
+    { binary: true }
+  ],
+  ['getVehiclePhoto', 'GET', '/api/v1/vehicles/{id}/photo', 'vehicles:read', { binary: true }],
+  [
+    'uploadVehiclePhoto',
+    'POST',
+    '/api/v1/vehicles/{id}/photo',
+    'vehicles:write',
+    { multipart: true }
+  ],
+  [
+    'deleteVehiclePhoto',
+    'DELETE',
+    '/api/v1/vehicles/{id}/photo',
+    'vehicles:write',
+    { confirmation: true }
+  ],
+  [
+    'listServiceRecords',
+    'GET',
+    '/api/v1/vehicles/{id}/service-records',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'createServiceRecord',
+    'POST',
+    '/api/v1/vehicles/{id}/service-records',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'getServiceRecord',
+    'GET',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:read'
+  ],
+  [
+    'updateServiceRecord',
+    'PUT',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  [
+    'deleteServiceRecord',
+    'DELETE',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  ['listMaintenance', 'GET', '/api/v1/operations/maintenance', 'maintenance:read'],
+  ['createMaintenance', 'POST', '/api/v1/vehicles/{id}/maintenance', 'maintenance:write'],
+  ['getMaintenance', 'GET', '/api/v1/operations/maintenance/{eventId}', 'maintenance:read'],
+  ['updateMaintenance', 'PATCH', '/api/v1/operations/maintenance/{eventId}', 'maintenance:write'],
+  [
+    'deleteMaintenance',
+    'DELETE',
+    '/api/v1/operations/maintenance/{eventId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  ['listDefects', 'GET', '/api/v1/operations/defects', 'operations:read'],
+  ['createDefect', 'POST', '/api/v1/operations/defects', 'operations:write'],
+  [
+    'completeMaintenance',
+    'POST',
+    '/api/v1/agent/operations/maintenance/{eventId}/complete',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  [
+    'completeDefect',
+    'POST',
+    '/api/v1/agent/operations/defects/{eventId}/complete',
+    'operations:write',
+    { confirmation: true }
+  ],
+  ['getReminderSettings', 'GET', '/api/v1/settings/reminders', 'reminders:read'],
+  ['updateReminderSettings', 'PUT', '/api/v1/settings/reminders', 'reminders:write'],
+  ['getVehicleReminderRecipients', 'GET', '/api/v1/vehicles/{id}/reminders', 'reminders:read'],
+  ['replaceVehicleReminderRecipients', 'PUT', '/api/v1/vehicles/{id}/reminders', 'reminders:write'],
+  [
+    'createMobileVehicleReminderRecipient',
+    'POST',
+    '/api/v1/vehicles/{id}/reminders',
+    'reminders:write'
+  ],
+  ['listContacts', 'GET', '/api/v1/contacts', 'reminders:read'],
+  ['createContact', 'POST', '/api/v1/contacts', 'reminders:write'],
+  ['deleteContact', 'DELETE', '/api/v1/contacts/{id}', 'reminders:write', { confirmation: true }],
+  [
+    'previewContactVerification',
+    'POST',
+    '/api/v1/contacts/{id}/verification/preview',
+    'reminders:write'
+  ],
+  [
+    'sendContactVerification',
+    'POST',
+    '/api/v1/contacts/{id}/verification/send',
+    'reminders:write',
+    { confirmation: true, idempotency: true }
+  ],
+  ['listBookings', 'GET', '/api/v1/bookings', 'maintenance:read'],
+  ['createBooking', 'POST', '/api/v1/bookings', 'maintenance:write', { idempotency: true }],
+  ['getBooking', 'GET', '/api/v1/bookings/{id}', 'maintenance:read'],
+  ['updateBookingStatus', 'PATCH', '/api/v1/bookings/{id}', 'maintenance:write'],
+  ['previewGarageEmail', 'POST', '/api/v1/bookings/{id}/garage-email/preview', 'maintenance:write'],
+  [
+    'sendGarageEmail',
+    'POST',
+    '/api/v1/bookings/{id}/garage-email/send',
+    'maintenance:write',
+    { confirmation: true, idempotency: true }
+  ],
+  ['getTollOperations', 'GET', '/api/v1/operations/tolls', 'operations:read'],
+  ['reviewTollCrossing', 'POST', '/api/v1/operations/tolls', 'operations:write'],
+  [
+    'listTollAccounts',
+    'GET',
+    '/api/v1/tolls/accounts',
+    'tolls:read',
+    { query: ['limit', 'offset', 'vehicleId'] }
+  ],
+  ['createTollAccount', 'POST', '/api/v1/tolls/accounts', 'tolls:write', { idempotency: true }],
+  [
+    'listTollTransactions',
+    'GET',
+    '/api/v1/tolls/transactions',
+    'tolls:read',
+    { query: ['limit', 'offset', 'vehicleId'] }
+  ],
+  [
+    'createTollTransaction',
+    'POST',
+    '/api/v1/tolls/transactions',
+    'tolls:write',
+    { idempotency: true }
+  ],
+  ['previewTollImport', 'POST', '/api/v1/tolls/imports/preview', 'tolls:read'],
+  ['applyTollImport', 'POST', '/api/v1/tolls/imports/apply', 'tolls:write', { idempotency: true }],
+  ['listTrackingSnapshots', 'GET', '/api/v1/operations/tracking', 'operations:read'],
+  [
+    'getWexRouteHistory',
+    'GET',
+    '/api/v1/operations/tracking/{vehicleId}/route',
+    'operations:read',
+    { query: ['period'] }
+  ],
+  ['getProfile', 'GET', '/api/v1/profile', 'profile:read'],
+  ['getDriverGuidance', 'GET', '/api/v1/driver-guidance', 'guidance:read'],
+  [
+    'downloadDriverGuidanceDocument',
+    'GET',
+    '/api/v1/driver-guidance/document',
+    'guidance:read',
+    { binary: true }
+  ],
+  ['downloadAccountExport', 'GET', '/api/v1/exports/account.json', 'exports:read'],
+  [
+    'downloadFleetSpreadsheet',
+    'GET',
+    '/api/v1/exports/fleet.xlsx',
+    'exports:read',
+    { binary: true }
+  ]
+];
+
+export const operations = Object.freeze(
+  Object.fromEntries(
+    definitions.map(([id, method, path, scope, options = {}]) => [
+      id,
+      Object.freeze({ id, method, path, scope, ...options })
+    ])
+  )
+);
+
+export const operationList = Object.freeze(Object.values(operations));

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.2.0",
-  "description": "Manage Fleetkeep vehicles and guarded fleet spreadsheet imports through the Fleetkeep API",
+  "version": "0.4.0",
+  "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {
     "fleetkeep": "fleetkeep.mjs"
   },
   "files": [
+    "api-command.mjs",
     "auth.mjs",
     "fleetkeep.mjs",
+    "operations.mjs",
     "README.md"
   ],
   "engines": {