ituran-axi 0.1.0 → 0.1.1

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
 
@@ -80,9 +77,9 @@ vehicles[3]{plate,age,status,speed,address}:
80
77
  "23456789",3m,parking,0,"1 Example Street, Tel Aviv"
81
78
  "34567890",3m,parking,0,"2 Example Street, Tel Aviv"
82
79
  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
80
+ - Run `ituran-axi where --all --page 2 --limit 3` for the next 3
81
+ - Run `ituran-axi vehicle <plate>` for one vehicle's driver and saved places
82
+ - Run `ituran-axi trips <plate> --since 24h` for where it went
86
83
 
87
84
  $ ituran-axi vehicle 00000000
88
85
  message: "Ituran found no vehicle 00000000: Entity was not found license_plate: 00000000"
@@ -90,12 +87,13 @@ code: not_found
90
87
  usage: "ituran-axi vehicle <plate> [--full]"
91
88
  ```
92
89
 
93
- [`comis/skills/ituran/recipes.md`](comis/skills/ituran/recipes.md) has tested shell combinations for common fleet questions.
90
+ [`docs/recipes.md`](docs/recipes.md) has tested shell combinations for common questions about the vehicles.
94
91
 
95
92
  ### Ituran's own rules
96
93
 
97
94
  ituran-axi handles these, and says so in its output where it matters:
98
95
  - 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.
99
97
  - BI reports ignore plate filters, so ituran-axi filters them itself.
100
98
  - 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
99
  - Alert lists repeat rows, which are removed and counted.
@@ -126,15 +124,17 @@ ituran-axi handles these, and says so in its output where it matters:
126
124
 
127
125
  ## Comis
128
126
 
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.
127
+ 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
128
 
131
129
  ## Development
132
130
 
133
131
  ```sh
132
+ git clone https://github.com/comisai/ituran-axi.git && cd ituran-axi
134
133
  npm ci
135
134
  npm run check # type-check, lint, unit and contract tests against a fake Ituran
136
135
  npm run build # dist/bin/ituran-axi.js
137
136
  npm run test:dist # contract and AXI-principle tests against the built CLI
137
+ npm link # optional: put this build on your PATH as ituran-axi
138
138
  ```
139
139
 
140
140
  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';
@@ -422,7 +422,7 @@ export function topHelp() {
422
422
  summary: c.summary,
423
423
  })),
424
424
  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`;
425
+ })}\n${helpBlock([`Run \`${BIN} help <command>\` for its flags`])}`;
426
426
  }
427
427
  export function commandHelp(spec) {
428
428
  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 = [];
@@ -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,13 @@
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, intFlag, joinedRows, listOutput, MAX_PAGE, open, recordOutput, rowsOf, str, totalOf, } from './common.js';
8
8
  const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
9
9
  const round1 = (v) => typeof v === 'number' ? Math.round(v * 10) / 10 : null;
10
10
  const RECENT_HOURS = 6;
11
+ /** Ituran fails an account-wide month of trips with HTTP 500, but answers a week. */
12
+ export const TRIP_SPAN_DAYS = 7;
11
13
  const LATE_NOTE = 'Ituran matches trips by their end time and lists a trip up to a few hours after it ends.';
12
14
  function windowFlags(values) {
13
15
  return {
@@ -96,14 +98,15 @@ export async function trips(input) {
96
98
  const columns = columnsFlag(values.fields, one
97
99
  ? ['id', 'start', 'end', 'km', 'driver']
98
100
  : ['id', 'plate', 'start', 'km', 'driver'], KNOWN);
99
- const fetchPage = async (page_number, page_size) => {
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) => {
100
103
  const json = await ctx.client.read({
101
104
  method: 'GET',
102
105
  path: api(ctx, '/trips'),
103
106
  query: {
104
107
  ...(plates.length ? { license_plates: plates } : {}),
105
- from_date: w.from,
106
- to_date: w.to,
108
+ from_date: span.from,
109
+ to_date: span.to,
107
110
  page_number,
108
111
  page_size,
109
112
  },
@@ -114,8 +117,8 @@ export async function trips(input) {
114
117
  rows: rowsOf(json, 'trips'),
115
118
  total: json === null ? 0 : totalOf(json),
116
119
  };
117
- };
118
- const got = await windowRows(fetchPage, page, limit);
120
+ });
121
+ const got = await joinedRows(lists, page, limit);
119
122
  const rows = got.rows.map(tripRow);
120
123
  const total = got.total;
121
124
  const whose = plates.length ? `for ${plates.join(' ')}` : 'for all vehicles';
@@ -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.1';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ituran-axi",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
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
  }