@lotics/cli 0.321.85 → 0.321.87

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.
@@ -91,23 +91,11 @@ Anything that imports, reconciles or de-duplicates has to decide identity, and w
91
91
  comparing displayed text — which is how one company arrives three times under three spellings. Name the key: a reference
92
92
  number, a tax id, a link plus a period. Then match on record ids and option aliases, never on rendered labels.
93
93
 
94
- ## Rows that belong together by their VALUES are linked by a rule
95
-
96
- A row that belongs to another by what it holds states a link the platform fills (`reference/link`, `fill`): a lesson to
97
- its teacher's month, a reading to the price in force on its day, a line arriving with a code to the row that code names.
98
- The link's `options_where` reads the row's own fields as `{ "$expr": "record.<field>" }`, and the platform keeps the link
99
- as either row changes:
100
-
101
- ```json
102
- "month": { "type": "link", "label": "Month", "table": "teacher_months", "multi": false, "pair": "lessons", "fill": true,
103
- "options_where": { "node_type": "group", "logic": "and", "children": [
104
- { "node_type": "condition", "field_key": "teacher", "operator": "has_any_of", "value": { "$expr": "record.teacher" } },
105
- { "node_type": "condition", "field_key": "month", "operator": "on", "value": { "$expr": "record.starts_at" } } ] } }
106
- ```
94
+ ## A row that belongs to another by its VALUES holds a link
107
95
 
108
- A rollup through the `pair` sums the lessons on the month's row as they are written, a lookup reads the row a lesson
109
- names, and the month's page lists its lessons. A workflow that reads the rows and copies a sum is stale between runs.
110
- Making the month's rows, and freezing one when it closes, stay acts.
96
+ An adjustment belongs to its person's month, a payment to its customer's statement: the row holds an ordinary link to
97
+ that row, set when the row is made — by the screen that adds it under its parent, or by a table workflow that finds the
98
+ parent from the row's values. A rollup through the link then reads live, and the link stays a person's to correct.
111
99
 
112
100
  ## A stage's moment is a date on the row
113
101
 
@@ -70,8 +70,8 @@ this host, give the person the file and a `person` drop link.
70
70
  - **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout
71
71
  you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:
72
72
  A0–A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page's own CSS,
73
- `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place
74
- of the whole `template`.
73
+ `@page { size: 50mm 30mm }`. A change may send `edits`, anchored replacements in the stored markup, in place
74
+ of the whole `template`; `template_file_id` names an uploaded text file holding the markup, in place of `template`.
75
75
  - **`pdf-form`** — an existing PDF filled in place. `set_template` with the uploaded `template_file_id`
76
76
  answers `page_count` and `pages` (each page's `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`
77
77
  and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with
@@ -21,7 +21,8 @@ get it right without the doc, the doc is noise.
21
21
  - `name` — what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into every title.**
22
22
  - `description` — what the doc is **and what to grep it for**: its vocabulary and the synonyms an ambiguous query would
23
23
  use. Surfaced in the listing before any body is read, and truncated at 200 characters.
24
- - `content` — Markdown.
24
+ - `content` — Markdown. `content_file_id` takes it from a stored text file in its place: upload the file with
25
+ `upload_file` (`files`) and pass the `file_id`.
25
26
  - `tags` *(optional)* — the labels someone would filter by, e.g. `["Hồ sơ NOXH", "Khoản 13"]`. Give **every** one that is
26
27
  true of the doc: a corpus is narrowed by intersecting tags, so a doc carrying one label is found down one path only.
27
28
  On a change the array **replaces** what is stored, so resend the labels it should keep.
package/docs/workflows.md CHANGED
@@ -37,6 +37,14 @@ and returns the calls planned, the return value, the failures and the papers ren
37
37
  `prev_data` and `changes`; a webhook or email trigger `trigger_payload`; an app trigger `record_id` and `preview_inputs`; a
38
38
  table or automation trigger also `live_reads` (an app's rehearsal always reads real data). A trial input its trigger does
39
39
  not supply is refused, naming the ones it takes. A rehearsal needs write scope: a key that reads data alone cannot make one.
40
+ A rehearsal's answer cuts a long list or text where it stands and says how much it kept; each step's output follows the
41
+ calls and the return value, cut to its first rows.
42
+
43
+ A stored workflow is changed without sending it whole: `edits` with its `workflow_id` are anchored replacements in the
44
+ source `get_workflow` returns (`[{ old_string, new_string }]`; `op` inserts before or after an anchor, or appends), and the
45
+ write is refused if the workflow moved since the version they were made against. A source not stored yet rides a file:
46
+ `source_file_id` takes it from a stored text file in place of `source`; write the source where you work, upload it with
47
+ `upload_file` (`files`) and pass the `file_id`.
40
48
 
41
49
  `delete: true` with a `workflow_id` removes a workflow, and is the one call that asks for approval; a replace asks for none,
42
50
  a step it drops included. `even_if_invoked` and `acknowledge_breaking_api_change` belong to an app workflow and are
@@ -54,6 +54,28 @@ A write is put back by writing the value `query_audit_logs` shows before the cha
54
54
  - `files`: bytes you hold locally. Each entry gets an `upload_url`, valid for 5 minutes, on the same host as your other calls; PUT the bytes to it and the response is the `file_id`. Where your sandbox allows no outbound request to that host (in Claude, a Team or Enterprise owner lists it under Admin settings → Capabilities), the PUT fails before it leaves: give the person the file with `person: true` instead.
55
55
  - `person: true`: returns a `drop_url`, valid for an hour, to give the person, and a `ticket_id` per file; once they say they dropped the files, call again with each `ticket_id` for its `file_id`.
56
56
 
57
+ ### Long text and many rows, as files
58
+
59
+ A stored text is changed by `edits`, never sent whole again: `set_workflow` (with `workflow_id`), `set_knowledge` and `set_template` (an html or email template's markup) take anchored replacements in the text their read returns.
60
+
61
+ A long text not stored yet rides a file. `set_workflow` takes `source_file_id` in place of `source`, `set_knowledge` takes `content_file_id` in place of `content`, and `set_template` takes `template_file_id` in place of an html or email `template`: write the text where you work, upload it with `upload_file` (`files`), and pass the `file_id` the upload answers.
62
+
63
+ Many rows come as a file. Over MCP, `query_records` with `as_file: true` sends the page as an embedded JSON file and lists no rows. The file is the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias, so code reads every row. Without a `limit` it takes the page maximum of 1,000 rows; `has_more` and `offset` page past it. On the CLI, `lotics run query_records '<json>' --json` prints the same answer.
64
+
65
+ Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
66
+
67
+ ```
68
+ { "records": [{ "name": "Lan", "amount": 4000000 }, { "name": "Minh", "amount": 2500000 }] }
69
+ ```
70
+
71
+ ```
72
+ { "record_ids": ["rec_…", "rec_…"], "field_keys": ["amount"], "rows": [[4000000], [2500000]] }
73
+ ```
74
+
75
+ The first is a create's file (`records`, or `field_keys` and `rows`), the second an update's. Write the file where you work, upload it with `upload_file` (`files`) and pass the `file_id`. A call takes 1,000 rows, and one a rule, a check or a value refuses writes none of them; `dry_run: true` writes nothing and answers the rows as they would be stored. A refusal names each refused row by its place in the file (`records[3]`, `rows[3]`) or by its record. An uploaded file that carried a call's rows or text is removed once the write lands, unless a record, a comment, a doc or a template holds it; a dry run leaves it for the write.
76
+
77
+ An update's dry run answers what would change: `changes`, each row's differing fields as they stand (`from`) and as they would be stored (`to`), a recomputed field among them, and `unchanged`, how many rows already hold the values sent. Over MCP, `as_file: true` sends that answer as a JSON file and lists no rows. On the CLI the rows go in the file that holds the call's arguments: `lotics run create_records @args.json`.
78
+
57
79
  ## Doing an operation
58
80
 
59
81
  `get_app` lists the app's acts as `act_<key>` (or the `workflow` an Act names) with what each takes. `run_app_workflow` with `dry_run: true` writes nothing
@@ -62,8 +84,8 @@ and says why (`agent_surface/a-refusal`).
62
84
 
63
85
  ## Writing records
64
86
 
65
- `create_records` takes 50 records a call, 20 or more of one shape in columnar form (`field_keys` once, then `rows`);
66
- `update_records` changes one or many. Both name fields and select options by alias, and `field_values` gives each
87
+ `create_records` takes 1,000 records a call, 20 or more of one shape in columnar form (`field_keys` once, then `rows`);
88
+ `update_records` changes one or many. Rows your code computed are written from a file (`rows_file_id`, § Files). Both name fields and select options by alias, and `field_values` gives each
67
89
  type's value. Every write meets the table's rules (`reference/write-rules`): every broken rule is listed at once, and a
68
90
  locked record answers under `blocked`. The owner's own lists (a menu with prices, customers, open orders) are rows of their
69
91
  tables, loaded this way after `set_tables`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.85",
3
+ "version": "0.321.87",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {