@fleetkeep/cli 0.7.0 → 0.8.1

package/README.md

@@ -105,6 +105,28 @@ maintenance updates cannot edit calculated forecast dates. There are no automati
 fuel-card feeds in the CLI. Wex credentials and Xero authorisation are entered in
 the website, never through CLI command arguments.
 
+## Toll statements and email forwarding
+
+```sh
+fleetkeep tolls forwarding
+fleetkeep tolls forwarding enable
+fleetkeep tolls import preview statement.csv
+fleetkeep tolls import apply statement.csv --confirm <digest-from-preview>
+```
+
+The forwarding command shows your private account address, recent imports and
+email delivery results. `enable` creates the address if needed. Forward CSV
+statement attachments to that address; the inbox is checked every 60 minutes.
+Each email accepts up to five attachments of 512 KiB each. Review unmatched
+vehicles and delivery messages in Fleetkeep. Keep the address private.
+
+For a local CSV, preview first and review the importable, duplicate and unmatched
+counts. Apply requires the exact preview digest and rejects a changed file before
+sending it. The CLI sends a stable idempotency key in the request header; use
+`--idempotency-key <key>` to choose your own and reuse it for an identical retry.
+Add `--json` to any command for the full API response. These commands require the
+matching toll API deployment. Statement preview requires `tolls:read`; applying an import and both forwarding commands require `tolls:write`.
+
 ## Safety model
 
 - `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.
@@ -168,3 +190,15 @@ 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.
+
+The private email-forwarding address requires `tolls:write`, including when reading it: anyone holding that address can submit statements. Read-only integrations do not receive it.
+
+CLI toll statement imports accept CSV files up to 256 KiB, the published API limit. Email forwarding accepts up to five PDF or CSV attachments of 512 KiB each. PDF charges always wait for approval. Preview and confirm the exact file digest before a CLI import is applied.
+
+### PDF invoices
+
+Forward the original PDF invoice to the account’s private forwarding address, or upload it in Toll Control. PDF charges wait for review before saving. CSV statements remain supported. Text-based GBP PDFs from recognised UK toll providers are supported; scanned, encrypted or ambiguous documents return an actionable error rather than guessed charges.
+
+`fleetkeep api call listTollPdfReviews` lists the signed-in account’s extracted rows and confirmation digests. Check the rows against the original invoice, then use `fleetkeep api call confirmTollPdfReview --data-file reviewed-pdf.json` with `batchId`, `confirmDigest`, `csv` and `confirmed: true`. The CSV is the reviewed structured data, not a file the customer needs to prepare. Keep the digest from the current review. Repeat confirmation is idempotent; a different account cannot read or confirm the invoice.
+
+These operations require a CLI release containing the PDF operation definitions. The backend candidate must be deployed before use.

package/fleetkeep.mjs

@@ -40,6 +40,10 @@ Usage:
   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 tolls forwarding [--json]
+  fleetkeep tolls forwarding enable [--json]
+  fleetkeep tolls import preview <file.csv> [--json]
+  fleetkeep tolls import apply <file.csv> --confirm <digest> [--idempotency-key <key>] [--json]
   fleetkeep api operations [--json]
   fleetkeep api call <operation-id> [API options]
 
@@ -445,6 +449,94 @@ function printImport(payload, jsonOutput) {
   }
 }
 
+function printTollForwarding(payload, jsonOutput) {
+  const lines = [
+    `Email forwarding: ${payload.available === false ? 'not available' : payload.enabled ? 'enabled' : 'not enabled'}`,
+    ...(payload.address ? [`Forward PDF invoices or CSV statements to: ${payload.address}`] : []),
+    'PDF charges wait for review: fleetkeep api call listTollPdfReviews',
+    `Inbox checked every ${payload.pollIntervalMinutes.toLocaleString('en-GB')} minutes.`,
+    ...(payload.enabled || payload.available === false
+      ? []
+      : ['To create your forwarding address: fleetkeep tolls forwarding enable']),
+    ...payload.recentImports.map(
+      (item) =>
+        `${item.fileName}: ${item.importedCount.toLocaleString('en-GB')} imported, ${item.unmatchedCount.toLocaleString('en-GB')} unmatched, ${item.duplicateCount.toLocaleString('en-GB')} duplicates (${item.status})`
+    ),
+    ...payload.recentDeliveries.map((item) => `${item.createdAt}: ${item.message}`)
+  ];
+  printJsonOr(payload, jsonOutput, lines.join('\n'));
+}
+
+async function tollImport(action, fileArg, args, jsonOutput) {
+  const allowed = new Set(
+    action === 'apply' ? ['--json', '--confirm', '--idempotency-key'] : ['--json']
+  );
+  for (let index = 0; index < args.length; index += 1) {
+    const name = args[index];
+    if (!allowed.has(name)) throw new Error(`Unknown option: ${name}.`);
+    if (name !== '--json') {
+      requiredValue(args, name);
+      index += 1;
+    }
+  }
+  const confirmDigest = requiredValue(args, '--confirm');
+  if (action === 'apply' && !/^[0-9a-f]{64}$/.test(confirmDigest || '')) {
+    throw new Error(
+      'Apply is blocked until --confirm contains the exact digest returned by preview.'
+    );
+  }
+  const idempotencyKey = requiredValue(args, '--idempotency-key');
+  if (!fileArg || fileArg.startsWith('--') || extname(fileArg).toLowerCase() !== '.csv') {
+    throw new Error('A .csv toll statement is required.');
+  }
+  const body = await spreadsheetPayload(fileArg);
+  if (Buffer.byteLength(body.csv, 'utf8') > 256 * 1024) {
+    throw new Error(
+      'CLI toll imports accept CSV files up to 256 KiB. Split a larger statement first.'
+    );
+  }
+  if (
+    action === 'apply' &&
+    createHash('sha256').update(body.csv, 'utf8').digest('hex') !== confirmDigest
+  ) {
+    throw new Error('The file does not match --confirm. Preview this file again before applying.');
+  }
+  const payload = await request(`/api/v1/tolls/imports/${action}`, {
+    method: 'POST',
+    body: action === 'apply' ? { ...body, confirmDigest } : body,
+    ...(action === 'apply'
+      ? { headers: { 'idempotency-key': idempotencyKey || `cli:tolls:${confirmDigest}` } }
+      : {})
+  });
+  if (jsonOutput) {
+    printJsonOr(payload, true, '');
+    return;
+  }
+  const count = (value) => value.toLocaleString('en-GB');
+  const lines =
+    action === 'preview'
+      ? [
+          `Source: ${payload.sourceName}`,
+          `Digest: ${payload.digest}`,
+          `Rows: ${count(payload.rowCount)}`,
+          `Importable: ${count(payload.importableCount)}`,
+          `Duplicates: ${count(payload.duplicateCount)}`,
+          `Unmatched vehicles: ${count(payload.unknownCount)}`,
+          '',
+          'No data was changed. To apply this exact file:',
+          `fleetkeep tolls import apply ${JSON.stringify(fileArg)} --confirm ${payload.digest}`
+        ]
+      : [
+          payload.replay
+            ? 'Toll import result replayed from the original request.'
+            : 'Toll import completed.',
+          `Imported: ${count(payload.imported)}`,
+          `Duplicates: ${count(payload.duplicates)}`,
+          `Unmatched vehicles: ${count(payload.unknown)}`
+        ];
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const jsonOutput = args.includes('--json');
@@ -458,6 +550,24 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'tolls' && args[1] === 'forwarding') {
+    const rest = args.slice(2).filter((arg) => arg !== '--json');
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== 'enable')) {
+      throw new Error('Use fleetkeep tolls forwarding [enable] [--json].');
+    }
+    const payload = await request(
+      '/api/v1/tolls/forwarding',
+      rest[0] === 'enable' ? { method: 'POST', body: {} } : {}
+    );
+    printTollForwarding(payload, jsonOutput);
+    return;
+  }
+
+  if (args[0] === 'tolls' && args[1] === 'import' && ['preview', 'apply'].includes(args[2])) {
+    await tollImport(args[2], args[3], args.slice(4), jsonOutput);
+    return;
+  }
+
   if (args[0] === 'costs' && args[1] === 'list') {
     const query = [];
     for (const name of ['from', 'to']) {

package/operations.mjs

@@ -1,5 +1,68 @@
 /** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
 const definitions = [
+  ['getFuelPrices', 'GET', '/api/fuel-prices', 'operations:read'],
+  [
+    'getFuelEconomy',
+    'GET',
+    '/api/fuel-economy',
+    'operations:read',
+    { query: ['year', 'make', 'model'] }
+  ],
+  [
+    'listFuelEconomyModels',
+    'GET',
+    '/api/fuel-economy/models',
+    'operations:read',
+    { query: ['year', 'make'] }
+  ],
+  [
+    'getChargingPrices',
+    'GET',
+    '/api/charging-prices',
+    'operations:read',
+    { query: ['region', 'days'] }
+  ],
+  ['getPublicChargingPrices', 'GET', '/api/public-charging-prices', 'operations:read'],
+  [
+    'replaceServiceSchedule',
+    'POST',
+    '/api/v1/vehicles/{id}/service-schedules',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'prepareServiceEvidenceRequest',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'recordServiceEvidenceContact',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/contacts',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'recordServiceEvidenceSubmission',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/submissions',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'reviewServiceEvidenceSubmission',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/submissions/{submissionId}/review',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  ['listDrivers', 'GET', '/api/v1/drivers', 'operations:read'],
+  ['getDriverActivity', 'GET', '/api/v1/drivers/activity', 'operations:read', { query: ['q'] }],
+  ['listDriverMemberships', 'GET', '/api/v1/driver-workspace', 'vehicles:read'],
+  ['getDriverWorkspace', 'GET', '/api/v1/driver-workspace/{id}', 'operations:read'],
+  ['getPushNotificationStatus', 'GET', '/api/v1/settings/push-notifications', 'reminders:read'],
   ['importProviderJobs', 'POST', '/api/v1/jobs/import', 'operations:write'],
   ['listFleetJobs', 'GET', '/api/v1/jobs', 'operations:read', { query: ['q'] }],
   ['saveFleetJob', 'POST', '/api/v1/jobs', 'operations:write'],
@@ -14,6 +77,7 @@ const definitions = [
   ],
   ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
   ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
+  ['searchVehicles', 'GET', '/api/v1/vehicles/search', 'vehicles:read', { query: ['q', 'limit'] }],
   ['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 }],
@@ -236,6 +300,10 @@ const definitions = [
     'tolls:write',
     { idempotency: true }
   ],
+  ['listTollPdfReviews', 'GET', '/api/v1/tolls/pdf-reviews', 'tolls:read'],
+  ['confirmTollPdfReview', 'POST', '/api/v1/tolls/pdf-reviews', 'tolls:write'],
+  ['getTollForwarding', 'GET', '/api/v1/tolls/forwarding', 'tolls:write'],
+  ['enableTollForwarding', 'POST', '/api/v1/tolls/forwarding', 'tolls:write'],
   ['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'],

package/package.json

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