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 +13 -13
- package/dist/cli/run.js +2 -2
- package/dist/commands/common.js +44 -0
- package/dist/commands/reports.js +1 -0
- package/dist/commands/trips.js +10 -7
- package/dist/output/toon.js +6 -2
- package/dist/time.js +19 -0
- package/dist/version.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# ituran-axi
|
|
2
2
|
|
|
3
3
|
[](https://github.com/comisai/ituran-axi/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/ituran-axi)
|
|
4
5
|
[](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.
|
|
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
|
-
|
|
29
|
-
cd ituran-axi
|
|
30
|
-
npm ci && npm run build && npm link
|
|
27
|
+
npm install -g ituran-axi
|
|
31
28
|
```
|
|
32
29
|
|
|
33
|
-
|
|
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
|
-
[`
|
|
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
|
-
|
|
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
|
-
})}\
|
|
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]) => ({
|
package/dist/commands/common.js
CHANGED
|
@@ -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 = [];
|
package/dist/commands/reports.js
CHANGED
|
@@ -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.`);
|
package/dist/commands/trips.js
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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:
|
|
106
|
-
to_date:
|
|
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
|
|
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';
|
package/dist/output/toon.js
CHANGED
|
@@ -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
|
-
/**
|
|
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.
|
|
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.
|
|
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.
|
|
52
|
+
"@biomejs/biome": "2.6.6",
|
|
53
53
|
"@types/node": "22.20.5",
|
|
54
54
|
"typescript": "7.0.2"
|
|
55
55
|
}
|