ituran-axi 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,6 +47,7 @@ ituran-axi vehicles [<text>] list, or find by plate digits, name,
47
47
  ituran-axi vehicle <plate> last position with address, current driver, saved places
48
48
  ituran-axi where [<plate>...] [--all] [--stale 2h] [--near <lat,lon> [--within <km>]]
49
49
  ituran-axi trips [<plate>...] [window] trips, matched by their end time
50
+ ituran-axi trips [window] --by plate one row per vehicle: trips, km, km a day, top speed
50
51
  ituran-axi trip <id> [--points] [--safety] [--speeding]
51
52
  ituran-axi totals [<plate>] [window] trip totals for the account or one vehicle
52
53
  ituran-axi odometer <plate>... | --all GPS odometer estimates with their reliability
@@ -93,7 +94,7 @@ usage: "ituran-axi vehicle <plate> [--full]"
93
94
 
94
95
  ituran-axi handles these, and says so in its output where it matters:
95
96
  - Trips are matched by their end time, and appear up to a few hours after they end.
96
- - Ituran fails a month of trips for the whole account in one request. ituran-axi reads a window longer than 7 days a week at a time, newest week first, and joins the pages.
97
+ - Ituran fails a month of trips for the whole account in one request. ituran-axi reads a window longer than 7 days a week at a time, newest week first, and joins the pages. `trips --by plate` reads every trip of the window this way and sums them per vehicle.
97
98
  - BI reports ignore plate filters, so ituran-axi filters them itself.
98
99
  - Operational reports take at most 5 plates and less than 3 days per request. ituran-axi splits the request, walks the pages and removes repeated rows.
99
100
  - Alert lists repeat rows, which are removed and counted.
package/dist/cli/run.js CHANGED
@@ -129,9 +129,14 @@ export const COMMANDS = [
129
129
  args: [{ name: '<plate>', required: false, variadic: true }],
130
130
  flags: {
131
131
  ...WINDOW,
132
+ by: {
133
+ type: 'string',
134
+ value: 'plate',
135
+ summary: 'One row per vehicle over the window: trips, km, km a day, top speed, driving time and days driven',
136
+ },
132
137
  fields: {
133
138
  ...FIELDS,
134
- summary: 'Columns: id, plate, start, end, km, driver, duration, idle, max_speed, safety, events, from, to, status, start_lat, start_lon, end_lat, end_lon',
139
+ summary: 'Columns: id, plate, start, end, km, driver, duration, idle, max_speed, safety, events, from, to, status, start_lat, start_lon, end_lat, end_lon; with --by plate: plate, trips, km, km_per_day, max_speed, driving, days',
135
140
  },
136
141
  limit: LIMIT,
137
142
  page: PAGE,
@@ -161,6 +161,24 @@ export async function walkAll(fetchPage, pageSize, cap = 20_000) {
161
161
  return { rows, total, partial: `stopped at ${cap} rows` };
162
162
  }
163
163
  }
164
+ /**
165
+ * Every row of one list: its first page gives the total, then the other
166
+ * pages are read side by side. Without a total it walks page by page.
167
+ */
168
+ export async function everyRow(fetchPage, size, cap) {
169
+ const first = await fetchPage(1, size);
170
+ if (first.total === null || first.rows.length < size)
171
+ return first.total === null && first.rows.length === size
172
+ ? walkAll(fetchPage, size, cap)
173
+ : first;
174
+ const wanted = Math.min(first.total, cap);
175
+ const pages = Math.ceil(wanted / size);
176
+ const rest = await Promise.all(Array.from({ length: pages - 1 }, (_, i) => fetchPage(i + 2, size)));
177
+ const rows = [first, ...rest].flatMap((page) => page.rows);
178
+ return first.total > cap
179
+ ? { rows, total: first.total, partial: `stopped at ${cap} rows` }
180
+ : { rows, total: first.total };
181
+ }
164
182
  export function plural(n, one, many = `${one}s`) {
165
183
  return `${n} ${n === 1 ? one : many}`;
166
184
  }
@@ -4,7 +4,8 @@
4
4
  import { AxiError, usage } from '../errors.js';
5
5
  import { normalizePlate } from '../plates.js';
6
6
  import { hoursMinutes, localTime, naiveMs, splitWindow, windowOf, } from '../time.js';
7
- import { account, api, columnsFlag, countLine, intFlag, joinedRows, listOutput, MAX_PAGE, open, recordOutput, rowsOf, str, totalOf, } from './common.js';
7
+ import { account, api, columnsFlag, countLine, everyRow, intFlag, joinedRows, listOutput, MAX_PAGE, open, recordOutput, rowsOf, str, totalOf, walkAll, } from './common.js';
8
+ import { listPage, WALK_PAGE } from './vehicles.js';
8
9
  const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
9
10
  const round1 = (v) => typeof v === 'number' ? Math.round(v * 10) / 10 : null;
10
11
  const RECENT_HOURS = 6;
@@ -86,20 +87,10 @@ const KNOWN = [
86
87
  'end_lat',
87
88
  'end_lon',
88
89
  ];
89
- export async function trips(input) {
90
- const ctx = open(input);
91
- const { values } = input;
92
- const plates = [...new Set(input.positionals.map(normalizePlate))];
93
- const acc = await account(ctx);
94
- const w = windowOf(windowFlags(values), acc.zone, ctx.now, '24h');
95
- const limit = intFlag(values.limit, 'limit', 20, 1, MAX_PAGE);
96
- const page = intFlag(values.page, 'page', 1, 1, 100_000);
90
+ /** One week's trips, page by page, for the plates given or the whole account. */
91
+ function tripPages(ctx, plates, span) {
97
92
  const one = plates.length === 1 ? plates[0] : undefined;
98
- const columns = columnsFlag(values.fields, one
99
- ? ['id', 'start', 'end', 'km', 'driver']
100
- : ['id', 'plate', 'start', 'km', 'driver'], KNOWN);
101
- // Long windows are read a week at a time, newest first, as one list.
102
- const lists = splitWindow(w, TRIP_SPAN_DAYS).map((span) => async (page_number, page_size) => {
93
+ return async (page_number, page_size) => {
103
94
  const json = await ctx.client.read({
104
95
  method: 'GET',
105
96
  path: api(ctx, '/trips'),
@@ -117,15 +108,36 @@ export async function trips(input) {
117
108
  rows: rowsOf(json, 'trips'),
118
109
  total: json === null ? 0 : totalOf(json),
119
110
  };
120
- });
111
+ };
112
+ }
113
+ export async function trips(input) {
114
+ const ctx = open(input);
115
+ const { values } = input;
116
+ const plates = [...new Set(input.positionals.map(normalizePlate))];
117
+ const acc = await account(ctx);
118
+ const w = windowOf(windowFlags(values), acc.zone, ctx.now, '24h');
119
+ const by = str(values.by);
120
+ if (by !== undefined) {
121
+ if (by !== 'plate')
122
+ throw usage('--by takes plate: one row per vehicle over the window.');
123
+ return tripsByPlate(input, ctx, acc, w, plates);
124
+ }
125
+ const limit = intFlag(values.limit, 'limit', 20, 1, MAX_PAGE);
126
+ const page = intFlag(values.page, 'page', 1, 1, 100_000);
127
+ const one = plates.length === 1 ? plates[0] : undefined;
128
+ const columns = columnsFlag(values.fields, one
129
+ ? ['id', 'start', 'end', 'km', 'driver']
130
+ : ['id', 'plate', 'start', 'km', 'driver'], KNOWN);
131
+ // Long windows are read a week at a time, newest first, as one list.
132
+ const lists = splitWindow(w, TRIP_SPAN_DAYS).map((span) => tripPages(ctx, plates, span));
121
133
  const got = await joinedRows(lists, page, limit);
122
134
  const rows = got.rows.map(tripRow);
123
135
  const total = got.total;
124
136
  const whose = plates.length ? `for ${plates.join(' ')}` : 'for all vehicles';
125
137
  const nowLocal = naiveMs(localTime(ctx.now, acc.zone));
126
138
  const recent = nowLocal - naiveMs(w.to) < RECENT_HOURS * 3600_000;
127
- const everyRow = total !== null && rows.length === total;
128
- const km = everyRow
139
+ const allShown = total !== null && rows.length === total;
140
+ const km = allShown
129
141
  ? Math.round(rows.reduce((s, r) => s + (typeof r.km === 'number' ? r.km : 0), 0) *
130
142
  10) / 10
131
143
  : null;
@@ -161,6 +173,117 @@ export async function trips(input) {
161
173
  narrower: 'ituran-axi trips <plate> --since 24h',
162
174
  });
163
175
  }
176
+ const BY_KNOWN = [
177
+ 'plate',
178
+ 'trips',
179
+ 'km',
180
+ 'km_per_day',
181
+ 'max_speed',
182
+ 'driving',
183
+ 'days',
184
+ ];
185
+ /** Trips read per week of a --by plate window before the totals say partial. */
186
+ const BY_CAP = 50_000;
187
+ /**
188
+ * One row per vehicle over the window: its trips, km, km a day (km over the
189
+ * window's days), top speed, driving time and days with a trip. Every trip of
190
+ * the window is read, a week at a time; with no plates, every vehicle of the
191
+ * account has a row, those that did not drive included.
192
+ */
193
+ async function tripsByPlate(input, ctx, acc, w, plates) {
194
+ const { values } = input;
195
+ const limit = intFlag(values.limit, 'limit', 20, 1, MAX_PAGE);
196
+ const page = intFlag(values.page, 'page', 1, 1, 100_000);
197
+ const columns = columnsFlag(values.fields, ['plate', 'trips', 'km', 'km_per_day', 'max_speed'], BY_KNOWN);
198
+ const [walks, fleet] = await Promise.all([
199
+ Promise.all(splitWindow(w, TRIP_SPAN_DAYS).map((span) => everyRow(tripPages(ctx, plates, span), MAX_PAGE, BY_CAP))),
200
+ plates.length
201
+ ? Promise.resolve(plates)
202
+ : walkAll(listPage(ctx), WALK_PAGE).then((all) => all.rows
203
+ .map((v) => str(v.license_plate))
204
+ .filter((p) => p !== undefined)),
205
+ ]);
206
+ const key = (plate) => plate.replace(/[\s-]+/g, '').toUpperCase();
207
+ const tally = new Map();
208
+ const fresh = (plate) => ({
209
+ plate,
210
+ trips: 0,
211
+ km: 0,
212
+ max: null,
213
+ seconds: 0,
214
+ days: new Set(),
215
+ });
216
+ for (const plate of fleet)
217
+ if (!tally.has(key(plate)))
218
+ tally.set(key(plate), fresh(plate));
219
+ // A trip on a week's or a page's edge can come twice; it counts once.
220
+ const seen = new Set();
221
+ let tripCount = 0;
222
+ for (const t of walks.flatMap((walk) => walk.rows)) {
223
+ const plate = str(t.license_plate);
224
+ if (!plate)
225
+ continue;
226
+ if (t.trip_id !== undefined && t.trip_id !== null) {
227
+ if (seen.has(t.trip_id))
228
+ continue;
229
+ seen.add(t.trip_id);
230
+ }
231
+ tripCount++;
232
+ const a = tally.get(key(plate)) ?? fresh(plate);
233
+ a.trips++;
234
+ if (typeof t.distance === 'number' && t.distance > 0)
235
+ a.km += t.distance;
236
+ if (typeof t.max_speed === 'number')
237
+ a.max = a.max === null ? t.max_speed : Math.max(a.max, t.max_speed);
238
+ if (typeof t.duration_in_seconds === 'number')
239
+ a.seconds += t.duration_in_seconds;
240
+ const day = (str(obj(t.start_location).timestamp) ?? str(obj(t.end_location).timestamp))?.slice(0, 10);
241
+ if (day)
242
+ a.days.add(day);
243
+ tally.set(key(plate), a);
244
+ }
245
+ const days = (naiveMs(w.to) - naiveMs(w.from) + 1000) /
246
+ 86_400_000;
247
+ const all = [...tally.values()]
248
+ .map((a) => ({
249
+ plate: a.plate,
250
+ trips: a.trips,
251
+ km: round1(a.km),
252
+ km_per_day: days > 0 ? round1(a.km / days) : null,
253
+ max_speed: a.max,
254
+ driving: hoursMinutes(a.seconds),
255
+ days: a.days.size,
256
+ }))
257
+ .sort((x, y) => y.km - x.km ||
258
+ String(x.plate).localeCompare(String(y.plate)));
259
+ const rows = all.slice((page - 1) * limit, page * limit);
260
+ const partial = walks.map((walk) => walk.partial).find(Boolean);
261
+ const totalKm = round1(all.reduce((s, r) => s + r.km, 0));
262
+ const summary = `${rows.length ? countLine(rows.length, all.length, 'vehicle') : '0 vehicles'} · ${tripCount} trips · ${totalKm} km over ${round1(days)} days`;
263
+ const shownTo = (page - 1) * limit + rows.length;
264
+ const nowLocal = naiveMs(localTime(ctx.now, acc.zone));
265
+ const recent = nowLocal - naiveMs(w.to) < RECENT_HOURS * 3600_000;
266
+ const help = [];
267
+ if (shownTo < all.length)
268
+ help.push(`Run \`ituran-axi trips ${[...plates, ...flagWords(values), '--by', 'plate', '--page', String(page + 1), ...(limit !== 20 ? ['--limit', String(limit)] : [])].join(' ')}\` for the next ${Math.min(limit, all.length - shownTo)}`);
269
+ help.push("Run `ituran-axi odometer --all` for each vehicle's odometer");
270
+ help.push(`Run \`ituran-axi trips <plate> ${flagWords(values).join(' ')}\` for one vehicle's trips`);
271
+ return listOutput({
272
+ key: 'vehicles',
273
+ summary,
274
+ head: {
275
+ window: `${w.from} to ${w.to}`,
276
+ zone: acc.zone,
277
+ ...(partial ? { partial: `trips ${partial}; the totals are low` } : {}),
278
+ ...(recent ? { note: LATE_NOTE } : {}),
279
+ },
280
+ rows,
281
+ columns,
282
+ help: help.slice(0, 3),
283
+ full: values.full === true,
284
+ narrower: 'ituran-axi trips --by plate --limit <n>',
285
+ });
286
+ }
164
287
  function flagWords(values) {
165
288
  const out = [];
166
289
  for (const f of ['since', 'from', 'to', 'date']) {
@@ -8,7 +8,7 @@ import { normalizePlate } from '../plates.js';
8
8
  import { age, ageMinutes, parseSpan } from '../time.js';
9
9
  import { account, api, columnsFlag, countLine, intFlag, listOutput, MAX_PAGE, open, recordOutput, rowsOf, shellWord, str, strings, totalOf, walkAll, windowRows, } from './common.js';
10
10
  const REALTIME = ['LastLocation', 'Driver', 'Places'];
11
- const WALK_PAGE = 500;
11
+ export const WALK_PAGE = 500;
12
12
  const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
13
13
  /** "Toyota Corolla 2022"; a model year of 0 means unset. */
14
14
  function modelOf(v) {
@@ -86,7 +86,7 @@ const KNOWN = [
86
86
  'places',
87
87
  'km',
88
88
  ];
89
- function listPage(ctx, realtime = []) {
89
+ export function listPage(ctx, realtime = []) {
90
90
  return async (page_number, page_size) => {
91
91
  const json = await ctx.client.read({
92
92
  method: 'GET',
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // Kept equal to package.json by test/unit/version.test.ts.
2
- export const VERSION = '0.1.1';
2
+ export const VERSION = '0.1.2';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ituran-axi",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "A read-only command-line tool that lets AI agents read Ituran vehicle tracking",
5
5
  "license": "MIT",
6
6
  "type": "module",