ituran-axi 0.1.0 → 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
@@ -1,6 +1,7 @@
1
1
  # ituran-axi
2
2
 
3
3
  [![CI](https://github.com/comisai/ituran-axi/actions/workflows/ci.yml/badge.svg)](https://github.com/comisai/ituran-axi/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/ituran-axi.svg)](https://www.npmjs.com/package/ituran-axi)
4
5
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
6
 
6
7
  A read-only command-line tool that lets AI agents read Ituran vehicle tracking: vehicles and their positions, trips, drivers, saved places, events, alerts, sensor readings, reports and safety grades.
@@ -8,12 +9,12 @@ A read-only command-line tool that lets AI agents read Ituran vehicle tracking:
8
9
  ituran-axi is an AXI, an [agent experience interface](https://axi.md). Every command:
9
10
  - prints compact [TOON](https://github.com/toon-format/toon) text on stdout, bounded in size;
10
11
  - refuses bad input and says exactly what is wrong;
11
- - ends with hints for the next command;
12
+ - ends with hints for the next command, as a TOON list, so the whole output decodes as one document;
12
13
  - only reads. It never changes Ituran settings or sends commands to a vehicle.
13
14
 
14
15
  It replaces [`ituran-mcp`](https://github.com/ituranlabs/ituran-mcp) for agents that have a shell: 24 commands instead of 152 tool schemas, which cost about 43,000 tokens per conversation. It was built to run inside Comis, behind the Comis Gate, and it also works on its own.
15
16
 
16
- > **Status:** early development (0.x). Every command is tested end to end against the production Ituran API. Release 0.1.0 to npm is in preparation.
17
+ > **Status:** early development (0.x). Every command is tested end to end against the production Ituran API.
17
18
 
18
19
  ## Requirements
19
20
 
@@ -22,15 +23,11 @@ It replaces [`ituran-mcp`](https://github.com/ituranlabs/ituran-mcp) for agents
22
23
 
23
24
  ## Install
24
25
 
25
- Until 0.1.0 is on npm, install from source:
26
-
27
26
  ```sh
28
- git clone https://github.com/comisai/ituran-axi.git
29
- cd ituran-axi
30
- npm ci && npm run build && npm link
27
+ npm install -g ituran-axi
31
28
  ```
32
29
 
33
- After the release, use `npm install -g ituran-axi`. Releases are published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so you can check that a package was built from this repository.
30
+ Each release is published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so you can check that it was built from this repository. To run from source instead, see [Development](#development).
34
31
 
35
32
  ## Configure
36
33
 
@@ -50,6 +47,7 @@ ituran-axi vehicles [<text>] list, or find by plate digits, name,
50
47
  ituran-axi vehicle <plate> last position with address, current driver, saved places
51
48
  ituran-axi where [<plate>...] [--all] [--stale 2h] [--near <lat,lon> [--within <km>]]
52
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
53
51
  ituran-axi trip <id> [--points] [--safety] [--speeding]
54
52
  ituran-axi totals [<plate>] [window] trip totals for the account or one vehicle
55
53
  ituran-axi odometer <plate>... | --all GPS odometer estimates with their reliability
@@ -80,9 +78,9 @@ vehicles[3]{plate,age,status,speed,address}:
80
78
  "23456789",3m,parking,0,"1 Example Street, Tel Aviv"
81
79
  "34567890",3m,parking,0,"2 Example Street, Tel Aviv"
82
80
  help[3]:
83
- Run `ituran-axi where --all --page 2 --limit 3` for the next 3
84
- Run `ituran-axi vehicle <plate>` for one vehicle's driver and saved places
85
- Run `ituran-axi trips <plate> --since 24h` for where it went
81
+ - Run `ituran-axi where --all --page 2 --limit 3` for the next 3
82
+ - Run `ituran-axi vehicle <plate>` for one vehicle's driver and saved places
83
+ - Run `ituran-axi trips <plate> --since 24h` for where it went
86
84
 
87
85
  $ ituran-axi vehicle 00000000
88
86
  message: "Ituran found no vehicle 00000000: Entity was not found license_plate: 00000000"
@@ -90,12 +88,13 @@ code: not_found
90
88
  usage: "ituran-axi vehicle <plate> [--full]"
91
89
  ```
92
90
 
93
- [`comis/skills/ituran/recipes.md`](comis/skills/ituran/recipes.md) has tested shell combinations for common fleet questions.
91
+ [`docs/recipes.md`](docs/recipes.md) has tested shell combinations for common questions about the vehicles.
94
92
 
95
93
  ### Ituran's own rules
96
94
 
97
95
  ituran-axi handles these, and says so in its output where it matters:
98
96
  - Trips are matched by their end time, and appear up to a few hours after they end.
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.
99
98
  - BI reports ignore plate filters, so ituran-axi filters them itself.
100
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.
101
100
  - Alert lists repeat rows, which are removed and counted.
@@ -126,15 +125,17 @@ ituran-axi handles these, and says so in its output where it matters:
126
125
 
127
126
  ## Comis
128
127
 
129
- [`comis/`](comis/README.md) holds the Comis connector bundle: the Gate catalog entry, the `ituran` agent skill and its recipes, and the pack wrapper. Inside Comis, the Gate signs in to Ituran and holds the token. The agent's workbench never sees the password or the token.
128
+ Comis ships `ituran-axi` in its `apps` pack, with the `ituran-read` skill and the `ituran` Gate service in its own repository. Inside Comis, the Gate signs in to Ituran and holds the token, and the agent's workbench never sees the password or the token. [`test/fixtures/comis-ituran-entry.json`](test/fixtures/comis-ituran-entry.json) is a copy of that Gate service; `test/contract/gate-entry.test.ts` checks that every request the AXI sends gets the token as a read, and that sign-in, device commands and writes are denied.
130
129
 
131
130
  ## Development
132
131
 
133
132
  ```sh
133
+ git clone https://github.com/comisai/ituran-axi.git && cd ituran-axi
134
134
  npm ci
135
135
  npm run check # type-check, lint, unit and contract tests against a fake Ituran
136
136
  npm run build # dist/bin/ituran-axi.js
137
137
  npm run test:dist # contract and AXI-principle tests against the built CLI
138
+ npm link # optional: put this build on your PATH as ituran-axi
138
139
  ```
139
140
 
140
141
  The live tests against the real Ituran API are opt-in, read-only, and need your own account; see [CONTRIBUTING.md](CONTRIBUTING.md#live-tests). The design and plans are in [`docs/`](docs/ituran-axi-design.md).
package/dist/cli/run.js CHANGED
@@ -14,7 +14,7 @@ import { totals, trip, trips } from '../commands/trips.js';
14
14
  import { vehicle, vehicles, where } from '../commands/vehicles.js';
15
15
  import { connected, readSettings } from '../config.js';
16
16
  import { AxiError, usage } from '../errors.js';
17
- import { errorText, render } from '../output/toon.js';
17
+ import { errorText, helpBlock, render } from '../output/toon.js';
18
18
  import { VERSION } from '../version.js';
19
19
  import { parseCommand } from './parse.js';
20
20
  import { BIN, commandName, usageLine, } from './table.js';
@@ -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,
@@ -422,7 +427,7 @@ export function topHelp() {
422
427
  summary: c.summary,
423
428
  })),
424
429
  settings: 'ITURAN_TOKEN, or ITURAN_USERNAME and ITURAN_PASSWORD; ITURAN_URL (default https://api.ituran.com/api/v2)',
425
- })}\nhelp[1]:\n Run \`${BIN} help <command>\` for its flags\n`;
430
+ })}\n${helpBlock([`Run \`${BIN} help <command>\` for its flags`])}`;
426
431
  }
427
432
  export function commandHelp(spec) {
428
433
  const flags = Object.entries(spec.flags).map(([name, f]) => ({
@@ -88,6 +88,50 @@ export async function windowRows(fetchPage, page, limit) {
88
88
  }
89
89
  return { rows: rows.slice(0, limit), total: a.total };
90
90
  }
91
+ /** A list's row count: the declared total, or the rows of a page that was not full. */
92
+ function countOf(got, pageSize) {
93
+ if (got.total !== null)
94
+ return got.total;
95
+ if (got.rows.length < pageSize)
96
+ return got.rows.length;
97
+ throw new AxiError('ituran_error', 'Ituran sent a page without a row count. Ask for a shorter window.');
98
+ }
99
+ /**
100
+ * Rows [offset, offset + limit) of several lists read as one, in order. The
101
+ * first page of each list gives its count; then only the pages that hold the
102
+ * wanted rows are read. The first list's first page is read at full size,
103
+ * since the wanted rows are usually there.
104
+ */
105
+ export async function joinedRows(lists, page, limit) {
106
+ const [only] = lists;
107
+ if (lists.length === 1 && only)
108
+ return windowRows(only, page, limit);
109
+ const size = Math.max(limit, MIN_PAGE);
110
+ const offset = (page - 1) * limit;
111
+ const firstSize = (i) => (i === 0 && offset < size ? size : MIN_PAGE);
112
+ const firsts = await Promise.all(lists.map((fetchPage, i) => fetchPage(1, firstSize(i))));
113
+ const counts = firsts.map((got, i) => countOf(got, firstSize(i)));
114
+ const starts = counts.map((_, i) => counts.slice(0, i).reduce((a, b) => a + b, 0));
115
+ const parts = await Promise.all(lists.map(async (fetchPage, i) => {
116
+ const from = Math.max(offset - starts[i], 0);
117
+ const to = Math.min(offset + limit - starts[i], counts[i]);
118
+ if (from >= to)
119
+ return [];
120
+ const first = firsts[i];
121
+ if (to <= first.rows.length)
122
+ return first.rows.slice(from, to);
123
+ const firstPage = Math.floor(from / size) + 1;
124
+ const rows = [];
125
+ for (let p = firstPage; (p - 1) * size < to; p++)
126
+ rows.push(...(await fetchPage(p, size)).rows);
127
+ const base = (firstPage - 1) * size;
128
+ return rows.slice(from - base, to - base);
129
+ }));
130
+ return {
131
+ rows: parts.flat().slice(0, limit),
132
+ total: counts.reduce((a, b) => a + b, 0),
133
+ };
134
+ }
91
135
  /** Every row, page by page, up to `cap` rows; stops early and says so when time runs out. */
92
136
  export async function walkAll(fetchPage, pageSize, cap = 20_000) {
93
137
  const rows = [];
@@ -117,6 +161,24 @@ export async function walkAll(fetchPage, pageSize, cap = 20_000) {
117
161
  return { rows, total, partial: `stopped at ${cap} rows` };
118
162
  }
119
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
+ }
120
182
  export function plural(n, one, many = `${one}s`) {
121
183
  return `${n} ${n === 1 ? one : many}`;
122
184
  }
@@ -375,6 +375,7 @@ export async function safety(input) {
375
375
  // This route counts any time today as the future: its grades cover
376
376
  // whole days up to yesterday, so the window ends there.
377
377
  const last = yesterday(ctx.now, acc.zone);
378
+ // biome-ignore lint/complexity/useMathMinMax: these are ISO date strings; Math.min would give NaN.
378
379
  const to = w.to < last ? w.to : last;
379
380
  if (w.from > to)
380
381
  throw usage(`Safety grades by group cover whole days up to yesterday, ${last}. Ask for a window that starts by then.`);
@@ -3,11 +3,14 @@
3
3
  // matters. Totals for the whole account take dates, not times.
4
4
  import { AxiError, usage } from '../errors.js';
5
5
  import { normalizePlate } from '../plates.js';
6
- import { hoursMinutes, localTime, naiveMs, windowOf } from '../time.js';
7
- import { account, api, columnsFlag, countLine, intFlag, listOutput, MAX_PAGE, open, recordOutput, rowsOf, str, totalOf, windowRows, } from './common.js';
6
+ import { hoursMinutes, localTime, naiveMs, splitWindow, windowOf, } from '../time.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;
12
+ /** Ituran fails an account-wide month of trips with HTTP 500, but answers a week. */
13
+ export const TRIP_SPAN_DAYS = 7;
11
14
  const LATE_NOTE = 'Ituran matches trips by their end time and lists a trip up to a few hours after it ends.';
12
15
  function windowFlags(values) {
13
16
  return {
@@ -84,26 +87,17 @@ const KNOWN = [
84
87
  'end_lat',
85
88
  'end_lon',
86
89
  ];
87
- export async function trips(input) {
88
- const ctx = open(input);
89
- const { values } = input;
90
- const plates = [...new Set(input.positionals.map(normalizePlate))];
91
- const acc = await account(ctx);
92
- const w = windowOf(windowFlags(values), acc.zone, ctx.now, '24h');
93
- const limit = intFlag(values.limit, 'limit', 20, 1, MAX_PAGE);
94
- 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) {
95
92
  const one = plates.length === 1 ? plates[0] : undefined;
96
- const columns = columnsFlag(values.fields, one
97
- ? ['id', 'start', 'end', 'km', 'driver']
98
- : ['id', 'plate', 'start', 'km', 'driver'], KNOWN);
99
- const fetchPage = async (page_number, page_size) => {
93
+ return async (page_number, page_size) => {
100
94
  const json = await ctx.client.read({
101
95
  method: 'GET',
102
96
  path: api(ctx, '/trips'),
103
97
  query: {
104
98
  ...(plates.length ? { license_plates: plates } : {}),
105
- from_date: w.from,
106
- to_date: w.to,
99
+ from_date: span.from,
100
+ to_date: span.to,
107
101
  page_number,
108
102
  page_size,
109
103
  },
@@ -115,14 +109,35 @@ export async function trips(input) {
115
109
  total: json === null ? 0 : totalOf(json),
116
110
  };
117
111
  };
118
- const got = await windowRows(fetchPage, page, limit);
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));
133
+ const got = await joinedRows(lists, page, limit);
119
134
  const rows = got.rows.map(tripRow);
120
135
  const total = got.total;
121
136
  const whose = plates.length ? `for ${plates.join(' ')}` : 'for all vehicles';
122
137
  const nowLocal = naiveMs(localTime(ctx.now, acc.zone));
123
138
  const recent = nowLocal - naiveMs(w.to) < RECENT_HOURS * 3600_000;
124
- const everyRow = total !== null && rows.length === total;
125
- const km = everyRow
139
+ const allShown = total !== null && rows.length === total;
140
+ const km = allShown
126
141
  ? Math.round(rows.reduce((s, r) => s + (typeof r.km === 'number' ? r.km : 0), 0) *
127
142
  10) / 10
128
143
  : null;
@@ -158,6 +173,117 @@ export async function trips(input) {
158
173
  narrower: 'ituran-axi trips <plate> --since 24h',
159
174
  });
160
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
+ }
161
287
  function flagWords(values) {
162
288
  const out = [];
163
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',
@@ -9,11 +9,15 @@ export const FIELD_LIMIT = 500;
9
9
  export const OUTPUT_LIMIT = 4000;
10
10
  /** --full output fits this many encoded bytes. */
11
11
  export const FULL_LIMIT = 262144;
12
- /** The indented help footer that follows the encoded body as AXI text. */
12
+ /**
13
+ * The help footer that follows the encoded body: one hint per line, as a TOON
14
+ * list (`- ` items, each quoted by the encoder when it must be), so the whole
15
+ * output decodes as one document.
16
+ */
13
17
  export function helpBlock(lines) {
14
18
  if (!lines.length)
15
19
  return '';
16
- return `help[${lines.length}]:\n${lines.map((l) => ` ${l}\n`).join('')}`;
20
+ return `help[${lines.length}]:\n${lines.map((l) => ` - ${encode(l)}\n`).join('')}`;
17
21
  }
18
22
  /** Encode a document (made visible first) and append help lines. */
19
23
  export function render(doc, help = []) {
package/dist/time.js CHANGED
@@ -145,6 +145,25 @@ export function windowOf(flags, zone, now, fallback, form = 'naive') {
145
145
  return { from: from.slice(0, 10), to: to.slice(0, 10) };
146
146
  return { from, to };
147
147
  }
148
+ /**
149
+ * A naive window cut into spans of at most `days` days, newest first, as
150
+ * Ituran lists trips. The spans meet without overlap: each ends one second
151
+ * before the next one starts.
152
+ */
153
+ export function splitWindow(w, days) {
154
+ const start = naiveMs(w.from);
155
+ const span = days * 86_400_000;
156
+ const out = [];
157
+ let end = naiveMs(w.to);
158
+ while (end - start >= span) {
159
+ const from = end - span + 1000;
160
+ out.push({ from: naiveFromMs(from), to: naiveFromMs(end) });
161
+ end = from - 1000;
162
+ }
163
+ if (end >= start)
164
+ out.push({ from: w.from, to: naiveFromMs(end) });
165
+ return out;
166
+ }
148
167
  /** How long ago a naive local time was: "3m", "2h", "5d", or null. */
149
168
  export function age(timestamp, now, zone) {
150
169
  if (typeof timestamp !== 'string')
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.0';
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.0",
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",
@@ -49,7 +49,7 @@
49
49
  "@toon-format/toon": "4.4.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@biomejs/biome": "2.5.15",
52
+ "@biomejs/biome": "2.6.6",
53
53
  "@types/node": "22.20.5",
54
54
  "typescript": "7.0.2"
55
55
  }