priority-axi 0.1.0 → 0.2.0

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
@@ -4,9 +4,10 @@
4
4
  [![npm](https://img.shields.io/npm/v/priority-axi.svg)](https://www.npmjs.com/package/priority-axi)
5
5
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
 
7
- A command-line tool that lets AI agents read and create records in Priority ERP through its REST API (OData).
7
+ A command-line tool that lets AI agents read, create and update records in Priority ERP through its REST API (OData).
8
8
 
9
9
  priority-axi is an AXI, an agent experience interface. Every command:
10
+
10
11
  - prints compact [TOON](https://github.com/toon-format/toon) text on stdout, bounded in size;
11
12
  - checks its input against the server's own metadata, and says exactly what is wrong;
12
13
  - ends with hints for the next command;
@@ -31,19 +32,20 @@ Each release is published from GitHub Actions with [npm provenance](https://docs
31
32
 
32
33
  ## Configure
33
34
 
34
- | Variable | Flag | Meaning |
35
- | --- | --- | --- |
36
- | `PRIORITY_URL` | | `https://host`, or the full service root `https://host/odata/Priority/<ini>/<company>` |
37
- | `PRIORITY_USER` | `--user` | The API username |
38
- | `PRIORITY_PASSWORD` | | The password. Inside Comis it is a placeholder that the Gate replaces. |
39
- | `PRIORITY_COMPANY` | `--company` | The company code |
40
- | `PRIORITY_INI` | `--ini` | The ini file in the URL. The default is `tabula.ini`. |
35
+ | Variable | Flag | Meaning |
36
+ | ------------------- | ----------- | -------------------------------------------------------------------------------------- |
37
+ | `PRIORITY_URL` | | `https://host`, or the full service root `https://host/odata/Priority/<ini>/<company>` |
38
+ | `PRIORITY_USER` | `--user` | The API username |
39
+ | `PRIORITY_PASSWORD` | | The password. Inside Comis it is a placeholder that the Gate replaces. |
40
+ | `PRIORITY_COMPANY` | `--company` | The company code |
41
+ | `PRIORITY_INI` | `--ini` | The ini file in the URL. The default is `tabula.ini`. |
41
42
 
42
43
  A flag overrides its variable. Plain `http://` is accepted only for `localhost` and `127.0.0.1`.
43
44
 
44
45
  ### Priority administrator setup
45
46
 
46
47
  The REST API reads only the screens that the administrator has opened to it. Ask them to:
48
+
47
49
  1. Add the screens you need to **Limited Access / API Forms**, for example CUSTOMERS, LOGPART and ORDERS. Their sub-screens, such as ORDERITEMS, come with them.
48
50
  2. Give the API user an API license, and only the privileges it needs.
49
51
 
@@ -60,6 +62,9 @@ priority-axi show <SCREEN> <key> [--with <SUB>]...
60
62
  priority-axi changes <SCREEN> --since 7d recent changes, on screens with a BPM status workflow
61
63
  priority-axi find <SCREEN> <words>... records by words in their name or description
62
64
  priority-axi create <SCREEN> --set F=V... [--line <SUB> F=V...]... [--dry-run]
65
+ priority-axi update <SCREEN> <key> --set F=V... [--dry-run] change a record
66
+ priority-axi add-line <SCREEN> <key> <SUB> F=V... [--dry-run] add a line to it
67
+ priority-axi update-line <SCREEN> <key> <SUB> <line-key> --set F=V... [--dry-run]
63
68
  priority-axi refresh rebuild the screen index
64
69
  priority-axi help [<command>] every flag of a command
65
70
  ```
@@ -98,6 +103,8 @@ priority-axi show ORDERS SO26000102 --with ORDERITEMS --with ORDERSTEXT
98
103
  priority-axi changes CUSTOMERS --since 7d
99
104
  priority-axi find LOGPART צינור ביוב 110
100
105
  priority-axi create ORDERS --set CUSTNAME=C1001 --line ORDERITEMS PARTNAME=P1 TQUANT=2 --dry-run
106
+ priority-axi add-line ORDERS SO26000102 ORDERITEMS PARTNAME=P1 TQUANT=2 --dry-run
107
+ priority-axi update-line ORDERS SO26000102 ORDERITEMS KLINE=1 --set TQUANT=3 --dry-run
101
108
  ```
102
109
 
103
110
  ### Filters
@@ -111,6 +118,7 @@ Always filter large document screens such as orders and invoices. Without a filt
111
118
  ### Finding records by words
112
119
 
113
120
  Priority cannot search inside text, so `find` keeps a local copy of a screen's catalog, refreshed daily: the key, description, unit, family and status. It matches as follows:
121
+
114
122
  - **Every word must appear.** A word matches the start of a word, after Hebrew prefix letters, so `ביוב` finds `לביוב`.
115
123
  - **Numbers match only as whole numbers.** `4` matches neither `4000` nor `SN4`.
116
124
  - **Spelling variants are ignored:** Hebrew points, final letter forms, and `״`/`׳` against `"`/`'`.
@@ -125,36 +133,40 @@ Records that are not in use are left out unless you pass `--all`. When no record
125
133
  - **Errors** print `message`, `code` and `usage` on stdout.
126
134
  - **Exit codes:** 0 on success, 1 on an error, 2 on a usage error.
127
135
 
128
- | Code | Meaning |
129
- | --- | --- |
130
- | `usage` | The command line is wrong; `usage` shows the right form |
131
- | `not_connected`, `missing_setting` | A setting is missing |
132
- | `auth_failed` | Priority refused the username or password |
133
- | `company_not_found` | The API user cannot reach that company |
134
- | `screen_not_enabled` | The screen is not in Limited Access / API Forms |
135
- | `not_found` | No record has that key |
136
- | `already_exists` | A create clashed with an existing key |
137
- | `priority_rejected` | Priority refused the request; its own message is shown |
138
- | `unsupported_query` | Priority cannot run that query |
139
- | `rate_limited` | Too many requests; wait and try again |
140
- | `held_for_approval`, `reconnect_needed`, `refused` | Inside Comis: the owner must approve, the owner must reconnect, or the Gate refused |
141
- | `unreachable`, `priority_error` | The server could not be reached, or it failed |
142
- | `output_too_large` | Even `--full` would exceed 256 KB; narrow the query |
143
- | `internal_error` | A bug in priority-axi; please [report it](https://github.com/comisai/priority-axi/issues) |
136
+ | Code | Meaning |
137
+ | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
138
+ | `usage` | The command line is wrong; `usage` shows the right form |
139
+ | `not_connected`, `missing_setting` | A setting is missing |
140
+ | `auth_failed` | Priority refused the username or password |
141
+ | `company_not_found` | The API user cannot reach that company |
142
+ | `screen_not_enabled` | The screen is not in Limited Access / API Forms |
143
+ | `not_found` | No record has that key |
144
+ | `already_exists` | A create clashed with an existing key |
145
+ | `priority_rejected` | Priority refused the request; its own message is shown |
146
+ | `unsupported_query` | Priority cannot run that query |
147
+ | `rate_limited` | Too many requests; wait and try again |
148
+ | `held_for_approval`, `reconnect_needed`, `refused` | Inside Comis: the owner must approve, the owner must reconnect, or the Gate refused |
149
+ | `unreachable`, `priority_error` | The server could not be reached, or it failed |
150
+ | `output_too_large` | Even `--full` would exceed 256 KB; narrow the query |
151
+ | `internal_error` | A bug in priority-axi; please [report it](https://github.com/comisai/priority-axi/issues) |
144
152
 
145
153
  ## Writes
146
154
 
147
- `create` checks every field against the metadata before it sends anything: the field must exist and be writable, and its value must have the right type and length.
155
+ `create`, `update`, `add-line` and `update-line` check every field against the metadata before they send anything: the field must exist and be writable, and its value must have the right type and length.
156
+
148
157
  - **Dry run:** `--dry-run` shows the request and how many API transactions it will cost: one per record and one per line.
149
- - **Sent once:** a create is never retried. Inside Comis, the Gate holds it until the owner approves it.
158
+ - **Sent once:** a write is never retried. Inside Comis, the Gate holds it until the owner approves it.
159
+ - **Updates name the record in the path:** `PATCH ORDERS('SO26000102')`, `POST ORDERS('SO26000102')/ORDERITEMS_SUBFORM` and `PATCH ORDERS('SO26000102')/ORDERITEMS_SUBFORM(KLINE=1)`. A key value is a typed literal; it may not hold a slash, a percent sign, a backslash, a control character or two dots in a row, and the record's key fields cannot be changed. Deleting is not supported.
150
160
  - **Fields the metadata does not mark:** Priority may require them, and then refuses with `priority_rejected` and its own message.
151
161
 
152
162
  ## Comis
153
163
 
154
- [`comis/`](comis/README.md) holds the Comis connector bundle:
155
- - the catalog entry and the Gate template;
156
- - the wrapper;
157
- - the agent skills, including one that turns a plumber's Hebrew order message into a draft sales order.
164
+ Comis ships priority-axi in its optional apps pack:
165
+
166
+ - a read skill, and a write skill that turns a plumber's Hebrew order message into a draft sales order for the owner's approval;
167
+ - a Gate catalog entry that injects the password only on the routes priority-axi uses, with a template for a server on a public host.
168
+
169
+ That integration lives in the Comis repository.
158
170
 
159
171
  ## Development
160
172
 
package/dist/cli/run.js CHANGED
@@ -7,12 +7,13 @@ import { find as findRecords } from '../commands/find.js';
7
7
  import { home } from '../commands/home.js';
8
8
  import { changes, get, show } from '../commands/read.js';
9
9
  import { refresh } from '../commands/refresh.js';
10
+ import { addLine, update, updateLine } from '../commands/update.js';
10
11
  import { AxiError, usage } from '../errors.js';
11
12
  import { errorText } from '../output/toon.js';
12
13
  import { VERSION } from '../version.js';
13
14
  import { parseCommand } from './parse.js';
14
15
  import { BIN, CONNECTION_FLAGS, commandName, usageLine, } from './table.js';
15
- export const DESCRIPTION = 'Read and create Priority ERP records over its REST API';
16
+ export const DESCRIPTION = 'Read, create and update Priority ERP records over its REST API';
16
17
  export const COMMANDS = [
17
18
  {
18
19
  name: '',
@@ -217,6 +218,70 @@ export const COMMANDS = [
217
218
  summary: 'Create a record; inside Comis the owner approves it first',
218
219
  run: create,
219
220
  },
221
+ {
222
+ name: 'update',
223
+ args: [
224
+ { name: '<SCREEN>', required: true },
225
+ { name: '<key>', required: true },
226
+ ],
227
+ flags: {
228
+ set: {
229
+ type: 'string',
230
+ multiple: true,
231
+ value: '<F=V>',
232
+ summary: 'A field to change',
233
+ },
234
+ 'dry-run': {
235
+ type: 'boolean',
236
+ summary: 'Check and show the request without sending it',
237
+ },
238
+ ...CONNECTION_FLAGS,
239
+ },
240
+ summary: 'Change fields of one record; inside Comis the owner approves it first',
241
+ run: update,
242
+ },
243
+ {
244
+ name: 'add-line',
245
+ args: [
246
+ { name: '<SCREEN>', required: true },
247
+ { name: '<key>', required: true },
248
+ { name: '<SUB>', required: true },
249
+ { name: '<F=V>', required: true, variadic: true },
250
+ ],
251
+ flags: {
252
+ 'dry-run': {
253
+ type: 'boolean',
254
+ summary: 'Check and show the request without sending it',
255
+ },
256
+ ...CONNECTION_FLAGS,
257
+ },
258
+ summary: "Add one line to a record's sub-screen; inside Comis the owner approves it first",
259
+ run: addLine,
260
+ },
261
+ {
262
+ name: 'update-line',
263
+ args: [
264
+ { name: '<SCREEN>', required: true },
265
+ { name: '<key>', required: true },
266
+ { name: '<SUB>', required: true },
267
+ { name: '<line-key>', required: true },
268
+ ],
269
+ flags: {
270
+ set: {
271
+ type: 'string',
272
+ multiple: true,
273
+ value: '<F=V>',
274
+ summary: 'A field of the line to change',
275
+ },
276
+ 'dry-run': {
277
+ type: 'boolean',
278
+ summary: 'Check and show the request without sending it',
279
+ },
280
+ ...CONNECTION_FLAGS,
281
+ },
282
+ summary: "Change one line of a record's sub-screen; inside Comis the owner approves it first",
283
+ run: updateLine,
284
+ },
220
285
  {
221
286
  name: 'refresh',
222
287
  args: [],
@@ -48,7 +48,7 @@ export function typedValue(field, raw, where) {
48
48
  return utc(raw, field.name);
49
49
  throw usage(`${field.name} has type ${field.type}, which create cannot set.`);
50
50
  }
51
- function assign(type, where, target, term) {
51
+ export function assign(type, where, target, term) {
52
52
  const t = parseWhere(term);
53
53
  if (t.op !== '=')
54
54
  throw usage(`Set fields with FIELD=VALUE; ${t.field} uses ${t.op}.`);
@@ -0,0 +1,124 @@
1
+ // update, add-line and update-line: change a record that exists. Each checks
2
+ // its fields against the index and sends one request, which inside Comis the
3
+ // Gate holds for the owner's approval. A record is named by its key in the
4
+ // path, NAME('KEY'), the only form the Gate's record type takes.
5
+ import { serviceRoot } from '../config.js';
6
+ import { usage } from '../errors.js';
7
+ import { send } from '../http.js';
8
+ import { resolveScreen, resolveSub, } from '../index/build.js';
9
+ import { recordSegment } from '../odata.js';
10
+ import { defaultColumns, tableRow } from '../output/shape.js';
11
+ import { render } from '../output/toon.js';
12
+ import { open, screenIndex, strings, tokenLine } from './common.js';
13
+ import { assign } from './create.js';
14
+ function fields(type, where, terms) {
15
+ const body = {};
16
+ for (const term of terms)
17
+ assign(type, where, body, term);
18
+ if (!Object.keys(body).length)
19
+ throw usage('Nothing to change: give --set FIELD=VALUE.');
20
+ for (const key of type.key)
21
+ if (key in body)
22
+ throw usage(`${key} names the record; an update cannot change it.`);
23
+ return body;
24
+ }
25
+ function keyOf(input, at, what) {
26
+ const key = input.positionals[at] ?? '';
27
+ if (!key)
28
+ throw usage(`Give ${what}.`);
29
+ return key;
30
+ }
31
+ async function write(input, s, w, command) {
32
+ const root = new URL(serviceRoot(s.settings)).pathname;
33
+ if (input.values['dry-run'] === true) {
34
+ return render({
35
+ dry_run: true,
36
+ request: `${w.method} ${root}/${w.path}`,
37
+ body: w.body,
38
+ transactions: 1,
39
+ }, [
40
+ `Run \`${tokenLine(command, input.tokens, ['dry-run'])}\` to send it; inside Comis the owner approves it first`,
41
+ ]);
42
+ }
43
+ // Sent once. A write is never retried; a held write is waited on with comis action wait.
44
+ const answer = await send(s.settings, {
45
+ method: w.method,
46
+ path: w.path,
47
+ body: w.body,
48
+ context: { screen: w.screen.name },
49
+ }, input.io.http);
50
+ const record = answer.json &&
51
+ typeof answer.json === 'object' &&
52
+ !Array.isArray(answer.json)
53
+ ? answer.json
54
+ : undefined;
55
+ return render({
56
+ [w.done]: w.screen.name,
57
+ request: `${w.method} ${root}/${w.path}`,
58
+ transactions: 1,
59
+ record: record
60
+ ? tableRow(w.shown, record, defaultColumns(w.shown, [record]), 500)
61
+ : null,
62
+ }, [
63
+ `Run \`priority-axi show ${w.screen.name} ${keyOf(input, 1, 'the key')} --with <SUB>\` to read it back`,
64
+ ]);
65
+ }
66
+ /** update <SCREEN> <key> --set F=V: change fields of one record. */
67
+ export async function update(input) {
68
+ const s = open(input);
69
+ const { index } = await screenIndex(s);
70
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
71
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
72
+ const body = fields(screen.type, screen.name, strings(input.values.set));
73
+ return write(input, s, {
74
+ method: 'PATCH',
75
+ screen,
76
+ path: recordSegment(screen.name, screen.type, key),
77
+ body,
78
+ shown: screen.type,
79
+ done: 'updated',
80
+ }, 'update');
81
+ }
82
+ /** add-line <SCREEN> <key> <SUB> <F=V>...: add one line to a record. */
83
+ export async function addLine(input) {
84
+ const s = open(input);
85
+ const { index } = await screenIndex(s);
86
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
87
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
88
+ const sub = resolveSub(index, screen, keyOf(input, 2, 'the sub-screen after the key'));
89
+ if (!sub.many)
90
+ throw usage(`${screen.name} > ${sub.name} holds one record; change it with update-line.`);
91
+ const where = `${screen.name} > ${sub.name}`;
92
+ const body = {};
93
+ for (const term of input.positionals.slice(3))
94
+ assign(sub.def, where, body, term);
95
+ if (!Object.keys(body).length)
96
+ throw usage(`Give the new line's fields after ${sub.name}, as FIELD=VALUE.`);
97
+ return write(input, s, {
98
+ method: 'POST',
99
+ screen,
100
+ path: `${recordSegment(screen.name, screen.type, key)}/${sub.nav}`,
101
+ body,
102
+ shown: sub.def,
103
+ done: 'added',
104
+ }, 'add-line');
105
+ }
106
+ /** update-line <SCREEN> <key> <SUB> <line-key> --set F=V: change one line. */
107
+ export async function updateLine(input) {
108
+ const s = open(input);
109
+ const { index } = await screenIndex(s);
110
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
111
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
112
+ const sub = resolveSub(index, screen, keyOf(input, 2, 'the sub-screen after the key'));
113
+ const line = keyOf(input, 3, `the line's key after ${sub.name}, such as ${sub.def.key.map((k) => `${k}=1`).join(',') || 'its number'}`);
114
+ const where = `${screen.name} > ${sub.name}`;
115
+ const body = fields(sub.def, where, strings(input.values.set));
116
+ return write(input, s, {
117
+ method: 'PATCH',
118
+ screen,
119
+ path: `${recordSegment(screen.name, screen.type, key)}/${recordSegment(sub.nav, sub.def, sub.def.key.length === 1 ? line.replace(new RegExp(`^${sub.def.key[0]}=`, 'i'), '') : line, true)}`,
120
+ body,
121
+ shown: sub.def,
122
+ done: 'updated',
123
+ }, 'update-line');
124
+ }
package/dist/http.js CHANGED
@@ -53,7 +53,9 @@ async function once(settings, call, deps) {
53
53
  // Priority 23.1 can drop the connection part way through an answer.
54
54
  throw new AxiError('unreachable', call.method === 'GET'
55
55
  ? 'Priority broke off its answer part way through. Try again with a smaller --limit or fewer --with sub-screens.'
56
- : 'Priority broke off its answer to the create, so it may have been saved. Check with priority-axi get or show before creating it again.');
56
+ : call.method === 'PATCH'
57
+ ? 'Priority broke off its answer to the update, so it may have been applied. Check with priority-axi show before updating it again.'
58
+ : 'Priority broke off its answer to the create, so it may have been saved. Check with priority-axi get or show before creating it again.');
57
59
  }
58
60
  const text = buffer.toString('utf8');
59
61
  let json;
package/dist/odata.js CHANGED
@@ -106,3 +106,47 @@ export function screenSegment(name) {
106
106
  }
107
107
  return name;
108
108
  }
109
+ // The longest record segment the Gate's key type takes.
110
+ const SEGMENT_MAX = 256;
111
+ /**
112
+ * A record's path segment, NAME(<key>), for an update. A screen with one key
113
+ * field takes its value as given; a compound key takes F=V pairs joined by
114
+ * commas, one per key field. Each value is a typed OData literal. A value may
115
+ * not hold a slash, a percent sign, a backslash, a control character or two dots:
116
+ * the Gate's record type refuses them, and so does this.
117
+ */
118
+ export function recordSegment(name, type, raw, named = false) {
119
+ screenSegment(name);
120
+ if (!type.key.length)
121
+ throw usage(`${name} has no key, so its records cannot be updated.`);
122
+ const values = [];
123
+ if (type.key.length === 1) {
124
+ values.push([type.key[0] ?? '', raw]);
125
+ }
126
+ else {
127
+ for (const pair of raw.split(',')) {
128
+ const t = /^([A-Za-z][A-Za-z0-9_]*)=(.*)$/s.exec(pair);
129
+ if (!t)
130
+ throw usage(`${name} has a compound key (${type.key.join(', ')}); give it as ${type.key.map((k) => `${k}=VALUE`).join(',')}.`);
131
+ values.push([t[1] ?? '', t[2] ?? '']);
132
+ }
133
+ const given = values.map(([f]) => f.toUpperCase()).sort();
134
+ const keys = [...type.key].map((k) => k.toUpperCase()).sort();
135
+ if (given.join() !== keys.join())
136
+ throw usage(`${name} has a compound key (${type.key.join(', ')}); give each once as ${type.key.map((k) => `${k}=VALUE`).join(',')}.`);
137
+ }
138
+ const parts = [];
139
+ for (const [fieldName, value] of values) {
140
+ if (!value)
141
+ throw usage(`The key ${fieldName} needs a value.`);
142
+ if (value.includes('..') || /[/%\\\p{Cc}]/u.test(value))
143
+ throw usage('A key value cannot hold a slash, a percent sign, a backslash, a control character or two dots in a row.');
144
+ const field = resolveField(type, name, fieldName);
145
+ const text = literal(field, value);
146
+ parts.push(type.key.length === 1 && !named ? text : `${field.name}=${text}`);
147
+ }
148
+ const segment = `${name}(${parts.join(',')})`;
149
+ if (segment.length > SEGMENT_MAX)
150
+ throw usage(`The record's key is longer than ${SEGMENT_MAX - name.length - 2} characters.`);
151
+ return segment;
152
+ }
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.2.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "priority-axi",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "A command-line tool that lets AI agents read and create Priority ERP records through the REST API",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -50,8 +50,8 @@
50
50
  "@toon-format/toon": "4.4.0"
51
51
  },
52
52
  "devDependencies": {
53
- "@biomejs/biome": "2.5.15",
54
- "@types/node": "22.20.5",
53
+ "@biomejs/biome": "2.6.5",
54
+ "@types/node": "26.6.6",
55
55
  "typescript": "7.0.2"
56
56
  }
57
57
  }