@fleetkeep/cli 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# 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.
+
+## 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.
+- 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.
+
+## Use
+
+Node.js 20 or newer is required. Sign in through Fleetkeep in your browser, then use the CLI:
+
+```sh
+fleetkeep auth login
+fleetkeep vehicles list
+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.

package/auth.mjs

@@ -0,0 +1,303 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile, chmod } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+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'];
+const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** @typedef {{ accessToken: string, refreshToken?: string | null, expiresAt: number }} StoredTokens */
+
+export function oauthConfig() {
+  const originValue = (process.env.FLEETKEEP_API_URL || DEFAULT_API_URL).trim().replace(/\/$/, '');
+  let originUrl;
+  try {
+    originUrl = new URL(originValue);
+  } catch {
+    throw new Error('FLEETKEEP_API_URL must be a valid HTTP or HTTPS origin.');
+  }
+  if (
+    !['http:', 'https:'].includes(originUrl.protocol) ||
+    originUrl.pathname !== '/' ||
+    originUrl.search ||
+    originUrl.hash ||
+    originUrl.username ||
+    originUrl.password
+  ) {
+    throw new Error('FLEETKEEP_API_URL must be an HTTP or HTTPS origin without a path.');
+  }
+  const origin = originUrl.origin;
+  const redirectUri = process.env.FLEETKEEP_OAUTH_REDIRECT_URI || DEFAULT_REDIRECT_URI;
+  const redirect = new URL(redirectUri);
+  if (redirect.protocol !== 'http:' || redirect.hostname !== '127.0.0.1' || !redirect.port) {
+    throw new Error('The Fleetkeep CLI OAuth callback must use http://127.0.0.1.');
+  }
+  return {
+    origin,
+    clientId: process.env.FLEETKEEP_OAUTH_CLIENT_ID || DEFAULT_CLIENT_ID,
+    redirectUri: redirect.href,
+    scopes: DEFAULT_SCOPES,
+    authorizationEndpoint: `${origin}/auth/oauth2/authorize`,
+    tokenEndpoint: `${origin}/auth/oauth2/token`,
+    revocationEndpoint: `${origin}/auth/oauth2/revoke`
+  };
+}
+
+function authFile() {
+  if (process.env.FLEETKEEP_AUTH_FILE) return process.env.FLEETKEEP_AUTH_FILE;
+  const configRoot = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(configRoot, 'fleetkeep', 'auth.json');
+}
+
+/** @returns {Promise<StoredTokens | null>} */
+export async function loadStoredTokens() {
+  try {
+    const value = JSON.parse(await readFile(authFile(), 'utf8'));
+    if (
+      value?.version !== 1 ||
+      typeof value.accessToken !== 'string' ||
+      !value.accessToken ||
+      (value.refreshToken !== null && typeof value.refreshToken !== 'string') ||
+      typeof value.expiresAt !== 'number'
+    ) {
+      throw new Error('invalid token file');
+    }
+    return value;
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+      return null;
+    throw new Error('Fleetkeep login is unreadable. Run `fleetkeep auth login` again.', {
+      cause: error
+    });
+  }
+}
+
+/** @param {StoredTokens} tokens */
+export async function saveStoredTokens(tokens) {
+  const file = authFile();
+  const directory = dirname(file);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  if (!process.env.FLEETKEEP_AUTH_FILE) await chmod(directory, 0o700);
+  const temporary = `${file}.${randomBytes(6).toString('hex')}.tmp`;
+  await writeFile(temporary, `${JSON.stringify({ ...tokens, version: 1 })}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+  await chmod(file, 0o600);
+}
+
+export async function clearStoredTokens() {
+  await rm(authFile(), { force: true });
+}
+
+function pkce() {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+export function authorizationRequest(config = oauthConfig()) {
+  const state = randomBytes(24).toString('base64url');
+  const { verifier, challenge } = pkce();
+  const url = new URL(config.authorizationEndpoint);
+  url.search = new URLSearchParams({
+    response_type: 'code',
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    scope: config.scopes.join(' '),
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    state,
+    resource: config.origin,
+    prompt: 'consent'
+  }).toString();
+  return { url, state, verifier };
+}
+
+/**
+ * @param {Record<string, string>} parameters
+ * @param {ReturnType<typeof oauthConfig>} config
+ * @returns {Promise<StoredTokens>}
+ */
+async function tokenRequest(parameters, config = oauthConfig()) {
+  const response = await fetch(config.tokenEndpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+    body: new URLSearchParams(parameters)
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || typeof payload.access_token !== 'string') {
+    const reason = typeof payload.error === 'string' ? payload.error : `HTTP ${response.status}`;
+    throw new Error(`Fleetkeep OAuth rejected the request (${reason}).`);
+  }
+  return {
+    accessToken: payload.access_token,
+    refreshToken:
+      typeof payload.refresh_token === 'string'
+        ? payload.refresh_token
+        : parameters.refresh_token || null,
+    expiresAt: Date.now() + (Number(payload.expires_in) || 3600) * 1000
+  };
+}
+
+/**
+ * @param {string} code
+ * @param {string} verifier
+ * @param {ReturnType<typeof oauthConfig>} config
+ */
+export async function exchangeAuthorizationCode(code, verifier, config = oauthConfig()) {
+  return tokenRequest(
+    {
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: config.redirectUri,
+      client_id: config.clientId,
+      code_verifier: verifier,
+      resource: config.origin
+    },
+    config
+  );
+}
+
+/**
+ * @param {StoredTokens} tokens
+ * @param {ReturnType<typeof oauthConfig>} config
+ */
+export async function refreshStoredTokens(tokens, config = oauthConfig()) {
+  if (!tokens.refreshToken) throw new Error('Your Fleetkeep session has expired. Sign in again.');
+  const refreshed = await tokenRequest(
+    {
+      grant_type: 'refresh_token',
+      refresh_token: tokens.refreshToken,
+      client_id: config.clientId,
+      scope: config.scopes.join(' '),
+      resource: config.origin
+    },
+    config
+  );
+  await saveStoredTokens(refreshed);
+  return refreshed;
+}
+
+export async function getAccessToken() {
+  const environmentToken = (process.env.FLEETKEEP_ACCESS_TOKEN || '').trim();
+  if (environmentToken) return environmentToken;
+  const stored = await loadStoredTokens();
+  if (!stored) {
+    throw new Error('Sign in with `fleetkeep auth login` or set FLEETKEEP_ACCESS_TOKEN.');
+  }
+  if (stored.expiresAt > Date.now() + 60_000) return stored.accessToken;
+  try {
+    return (await refreshStoredTokens(stored)).accessToken;
+  } catch (error) {
+    await clearStoredTokens();
+    throw error;
+  }
+}
+
+/** @param {string} url */
+function openBrowser(url) {
+  /** @type {[string, string[]]} */
+  const command =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['rundll32.exe', ['url.dll,FileProtocolHandler', url]]
+        : ['xdg-open', [url]];
+  const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+}
+
+export async function login({ noBrowser = false } = {}) {
+  if ((process.env.FLEETKEEP_ACCESS_TOKEN || '').trim()) {
+    throw new Error('Unset FLEETKEEP_ACCESS_TOKEN before saving a CLI login.');
+  }
+  const config = oauthConfig();
+  const request = authorizationRequest(config);
+  const redirect = new URL(config.redirectUri);
+  /** @type {NodeJS.Timeout | undefined} */
+  let timeout;
+  /** @type {import('node:http').Server | undefined} */
+  let server;
+  /** @type {Promise<string>} */
+  const callback = new Promise((resolve, reject) => {
+    server = createServer((incoming, response) => {
+      const url = new URL(incoming.url || '/', config.redirectUri);
+      if (url.pathname !== redirect.pathname) {
+        response.writeHead(404).end('Not found');
+        return;
+      }
+      const error = url.searchParams.get('error');
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      if (error || !code || state !== request.state) {
+        response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+        response.end('Fleetkeep sign-in was not completed. Return to the terminal.');
+        reject(new Error(error || 'Fleetkeep sign-in response was invalid.'));
+        return;
+      }
+      response.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+      response.end('Fleetkeep sign-in complete. You can close this window.');
+      resolve(code);
+    });
+    server.listen(Number(redirect.port), redirect.hostname);
+    timeout = setTimeout(
+      () => reject(new Error('Fleetkeep sign-in timed out. Run `fleetkeep auth login` again.')),
+      Number(process.env.FLEETKEEP_AUTH_TIMEOUT_MS) || AUTH_TIMEOUT_MS
+    );
+  });
+
+  try {
+    await /** @type {Promise<void>} */ (
+      new Promise((resolve, reject) => {
+        if (!server) reject(new Error('Fleetkeep callback server did not start.'));
+        else if (server.listening) resolve();
+        else {
+          server.once('listening', resolve);
+          server.once('error', reject);
+        }
+      })
+    );
+    process.stdout.write(`Open this URL to sign in:\n${request.url.href}\n`);
+    if (!noBrowser) openBrowser(request.url.href);
+    const code = await callback;
+    const tokens = await exchangeAuthorizationCode(code, request.verifier, config);
+    await saveStoredTokens(tokens);
+    process.stdout.write('Signed in to Fleetkeep.\n');
+  } finally {
+    clearTimeout(timeout);
+    await /** @type {Promise<void>} */ (
+      new Promise((resolve) => (server?.listening ? server.close(() => resolve()) : resolve()))
+    );
+  }
+}
+
+export async function authStatus() {
+  if ((process.env.FLEETKEEP_ACCESS_TOKEN || '').trim()) return 'Using FLEETKEEP_ACCESS_TOKEN.';
+  const stored = await loadStoredTokens();
+  if (!stored) return 'Not signed in.';
+  if (stored.expiresAt <= Date.now() && !stored.refreshToken) return 'Session expired.';
+  return 'Signed in to Fleetkeep.';
+}
+
+export async function logout() {
+  const stored = await loadStoredTokens();
+  if (stored?.refreshToken) {
+    const config = oauthConfig();
+    await fetch(config.revocationEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        token: stored.refreshToken,
+        token_type_hint: 'refresh_token',
+        client_id: config.clientId
+      })
+    }).catch(() => null);
+  }
+  await clearStoredTokens();
+  process.stdout.write('Signed out of Fleetkeep on this machine.\n');
+}

package/fleetkeep.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { basename, extname, resolve } from 'node:path';
+import { authStatus, getAccessToken, login, logout } from './auth.mjs';
+
+const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
+
+function usage() {
+  return `Fleetkeep CLI
+
+Usage:
+  fleetkeep auth login [--no-browser]
+  fleetkeep auth status
+  fleetkeep auth logout
+  fleetkeep vehicles list [--json]
+  fleetkeep import preview <file.csv|file.xlsx> [--json]
+  fleetkeep import apply <file.csv|file.xlsx> --confirm <digest> [--idempotency-key <key>] [--json]
+
+Environment:
+  FLEETKEEP_ACCESS_TOKEN  Optional OAuth token override for automation
+  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.`;
+}
+
+function fail(message, exitCode = 1) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = exitCode;
+}
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  return value && !value.startsWith('--') ? value : '';
+}
+
+function apiOrigin() {
+  const value = (process.env.FLEETKEEP_API_URL || DEFAULT_API_URL).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 !== '/') {
+    throw new Error('FLEETKEEP_API_URL must be an HTTP or HTTPS origin without a path.');
+  }
+  return url.origin;
+}
+
+async function request(path, { method = 'GET', body }) {
+  const token = await getAccessToken();
+  const response = await fetch(`${apiOrigin()}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: 'application/json',
+      ...(body ? { 'content-type': 'application/json' } : {})
+    },
+    ...(body ? { body: JSON.stringify(body) } : {})
+  });
+  const payload = 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}`);
+  }
+  return payload;
+}
+
+async function spreadsheetPayload(fileArg) {
+  if (!fileArg || fileArg.startsWith('--')) throw new Error('A .csv or .xlsx file is required.');
+  const path = resolve(fileArg);
+  const extension = extname(path).toLowerCase();
+  if (!['.csv', '.xlsx'].includes(extension)) {
+    throw new Error('Fleetkeep imports .csv and .xlsx files. Save older .xls files first.');
+  }
+  const bytes = await readFile(path);
+  const sourceName = basename(path);
+  return extension === '.csv'
+    ? { sourceName, csv: bytes.toString('utf8') }
+    : { sourceName, contentBase64: bytes.toString('base64') };
+}
+
+function printPreview(payload, jsonOutput, fileArg) {
+  if (jsonOutput) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  const p = payload.preview;
+  process.stdout.write(
+    [
+      `Source: ${payload.sourceName}`,
+      `Digest: ${payload.digest}`,
+      `Rows: ${p.detectedVehicleCount}`,
+      `Valid registrations: ${p.validRegistrations}`,
+      `Invalid registrations: ${p.invalidRegistrations}`,
+      `Duplicate registrations: ${p.duplicateRegistrations}`,
+      `Over self-serve limit: ${p.overSelfServeLimit ? 'yes' : 'no'}`,
+      '',
+      'No data was changed. To apply this exact file:',
+      `fleetkeep import apply ${JSON.stringify(fileArg)} --confirm ${payload.digest}`
+    ].join('\n') + '\n'
+  );
+}
+
+function printImport(payload, jsonOutput) {
+  if (jsonOutput) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  const summary = payload.summary;
+  process.stdout.write(
+    [
+      payload.replayed ? 'Import result replayed from the original request.' : 'Import completed.',
+      `Added: ${summary.added}`,
+      `Existing vehicles updated with equipment: ${summary.updated}`,
+      `Duplicates or unchanged: ${summary.duplicates}`,
+      `Invalid: ${summary.invalid}`,
+      `Database errors: ${summary.dbErrors}`
+    ].join('\n') + '\n'
+  );
+  for (const outcome of payload.outcomes) {
+    process.stdout.write(`${outcome.registration || `line ${outcome.line}`}: ${outcome.message}\n`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const jsonOutput = args.includes('--json');
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  if (args[0] === 'auth' && args[1] === 'login') {
+    await login({ noBrowser: args.includes('--no-browser') });
+    return;
+  }
+
+  if (args[0] === 'auth' && args[1] === 'status') {
+    process.stdout.write(`${await authStatus()}\n`);
+    return;
+  }
+
+  if (args[0] === 'auth' && args[1] === 'logout') {
+    await logout();
+    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`);
+    else {
+      for (const vehicle of payload.vehicles || []) {
+        process.stdout.write(
+          `${vehicle.registration}\t${vehicle.label || ''}\t${vehicle.make || ''}\n`
+        );
+      }
+    }
+    return;
+  }
+
+  if (args[0] === 'import' && args[1] === 'preview') {
+    const body = await spreadsheetPayload(args[2]);
+    const payload = await request('/api/v1/imports/vehicles/preview', {
+      method: 'POST',
+      body
+    });
+    printPreview(payload, jsonOutput, args[2]);
+    return;
+  }
+
+  if (args[0] === 'import' && args[1] === 'apply') {
+    const confirmDigest = option(args, '--confirm');
+    if (!confirmDigest) {
+      throw new Error(
+        'Apply is blocked until --confirm contains the exact digest returned by preview.'
+      );
+    }
+    const body = await spreadsheetPayload(args[2]);
+    const idempotencyKey = option(args, '--idempotency-key') || `cli:${confirmDigest}`;
+    const payload = await request('/api/v1/imports/vehicles/apply', {
+      method: 'POST',
+      body: { ...body, confirmDigest, idempotencyKey }
+    });
+    printImport(payload, jsonOutput);
+    return;
+  }
+
+  throw new Error(`Unknown command.\n\n${usage()}`);
+}
+
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)));

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@fleetkeep/cli",
+  "version": "0.1.0",
+  "description": "Preview and apply Fleetkeep fleet spreadsheet imports through the Fleetkeep API",
+  "type": "module",
+  "bin": {
+    "fleetkeep": "fleetkeep.mjs"
+  },
+  "files": [
+    "auth.mjs",
+    "fleetkeep.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}