@fleetkeep/cli 0.4.0 → 0.5.0

package/README.md

@@ -5,6 +5,40 @@ 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.
 
+## Shared jobs and running costs
+
+Friendly commands return JSON, including missing-data and stale-tracking fields:
+
+```sh
+fleetkeep costs list --from 2026-09-01 --to 2026-09-30
+fleetkeep costs record --data-file expense.json
+fleetkeep drivers activity --search JOB-42
+fleetkeep tracking list
+fleetkeep tracking route <vehicle-id> --period 7d
+```
+
+Driver activity returns up to 100 journeys and 100 inspections from the company's
+central record. Search filters journeys by job reference, driver or registration;
+inspections remain the latest 100. The activity endpoint must be deployed before
+using this command. Route history requires a supported connected tracker.
+Expense files use the fields below; keep the same UUID and body when retrying.
+
+`fleetkeep jobs list --search JOB-42` finds company jobs. Use
+`fleetkeep jobs save JOB-42 --title "Depot installation"` to create or update a reference,
+and `fleetkeep jobs close <job-id>` or `reopen <job-id>` to change its availability.
+Closing a job preserves its journey history. These owner operations need an active Fleet plan.
+
+`fleetkeep api call getRunningCosts --query from=2026-09-01 --query to=2026-09-30`
+returns recorded GBP costs and missing-data flags. `recordFleetExpense` accepts a JSON body
+with `id` (UUID), `vehicleId`, `incurredOn`, `category`, `amount` (GBP decimal string) and
+`description`. Reuse the UUID and identical body on retries. Dates span up to one year.
+Supported categories are fuel, insurance, repair, parking and other. Negative amounts record
+refunds or corrections. Service costs and recorded GBP tolls are included separately, so do
+not enter them again. Account JSON exports include jobs, journeys and additional costs.
+
+Xero authorisation and bill review take place in the web portal. Saved SHVL grants and
+credentials are not transferred between products or customer workspaces.
+
 ## Safety model
 
 - `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.

package/fleetkeep.mjs

@@ -21,9 +21,18 @@ Usage:
   fleetkeep vehicles delete <vehicle-id> [--confirmation <server-token>] [--json]
   fleetkeep vehicles bulk-add <registration>... [--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]
+  fleetkeep costs record --data-file <expense.json>
+  fleetkeep tracking list [--json]
+  fleetkeep tracking route <vehicle-id> [--period <period>] [--json]
   fleetkeep drivers invite <email> --name <name> [--json]
   fleetkeep drivers resend <driver-id> [--json]
   fleetkeep drivers revoke <driver-id> [--json]
+  fleetkeep jobs list [--search <reference>] [--json]
+  fleetkeep jobs save <reference> --title <title> [--json]
+  fleetkeep jobs close <job-id> [--json]
+  fleetkeep jobs reopen <job-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]
@@ -293,6 +302,46 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'costs' && args[1] === 'list') {
+    const query = [];
+    for (const name of ['from', 'to']) {
+      const value = option(args, `--${name}`);
+      if (value) query.push('--query', `${name}=${value}`);
+    }
+    await runApiCommand(['call', 'getRunningCosts', ...query]);
+    return;
+  }
+  if (args[0] === 'costs' && args[1] === 'record') {
+    const file = option(args, '--data-file');
+    if (!file) throw new Error('--data-file is required. Reuse the expense UUID on retries.');
+    await runApiCommand(['call', 'recordFleetExpense', '--data-file', file]);
+    return;
+  }
+  if (args[0] === 'tracking' && args[1] === 'list') {
+    await runApiCommand(['call', 'listTrackingSnapshots']);
+    return;
+  }
+  if (args[0] === 'tracking' && args[1] === 'route') {
+    if (!args[2] || args[2].startsWith('--')) throw new Error('A vehicle ID is required.');
+    const period = option(args, '--period');
+    await runApiCommand([
+      'call',
+      'getWexRouteHistory',
+      '--path',
+      `vehicleId=${args[2]}`,
+      ...(period ? ['--query', `period=${period}`] : [])
+    ]);
+    return;
+  }
+  if (args[0] === 'drivers' && args[1] === 'activity') {
+    const payload = await request(
+      `/api/v1/drivers/activity?q=${encodeURIComponent(option(args, '--search') || '')}`,
+      {}
+    );
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
   if (args[0] === 'auth' && args[1] === 'login') {
     await login({ noBrowser: args.includes('--no-browser') });
     return;
@@ -409,6 +458,30 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'jobs' && ['list', 'save', 'close', 'reopen'].includes(args[1])) {
+    const action = args[1];
+    let payload;
+    if (action === 'list') {
+      payload = await request(
+        `/api/v1/jobs?q=${encodeURIComponent(option(args, '--search') || '')}`,
+        {}
+      );
+    } else {
+      if (!args[2] || args[2].startsWith('--'))
+        throw new Error('A job reference or ID is required.');
+      if (action === 'save' && !option(args, '--title')) throw new Error('--title is required.');
+      payload = await request('/api/v1/jobs', {
+        method: 'POST',
+        body:
+          action === 'save'
+            ? { action: 'save', reference: args[2], title: option(args, '--title') }
+            : { action: 'status', id: args[2], status: action === 'close' ? 'closed' : 'active' }
+      });
+    }
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    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`);

package/operations.mjs

@@ -1,5 +1,17 @@
 /** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
 const definitions = [
+  ['importProviderJobs', 'POST', '/api/v1/jobs/import', 'operations:write'],
+  ['listFleetJobs', 'GET', '/api/v1/jobs', 'operations:read', { query: ['q'] }],
+  ['saveFleetJob', 'POST', '/api/v1/jobs', 'operations:write'],
+  ['getRunningCosts', 'GET', '/api/v1/costs', 'operations:read', { query: ['from', 'to'] }],
+  ['recordFleetExpense', 'POST', '/api/v1/costs', 'operations:write'],
+  [
+    'listDriverJobs',
+    'GET',
+    '/api/v1/driver-workspace/{id}/jobs',
+    'operations:read',
+    { query: ['q'] }
+  ],
   ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
   ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
   ['getVehicle', 'GET', '/api/v1/vehicles/{id}', 'vehicles:read'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {