ekwo-os 0.20.0 → 0.21.2

package/README.md

@@ -171,7 +171,11 @@ project reports what was already there and creates nothing a second time.
 | `ekwo contact duplicates` | The pairs of contacts that are probably one party, strongest first, through `suggest_duplicate_contacts()`: which one to keep, a score, and the evidence — the same VAT or registration number, the same bank account, the words of the name weighed by how few contacts carry them. Writes nothing. |
 | `ekwo contact merge <keep> <absorb>` | One party created twice — two spellings, two imports — joined through `merge_contacts()`: everything that names the second, posted lines and issued documents included, names the first; the first takes the fields it left empty; the second is retired, never deleted, and named by nothing again. By name or id. |
 | `ekwo doc new` / `doc line add` | A draft document — any kind, with `--type` — and one more line on it. A draft books nothing. `ekwo invoice` is the old name of `ekwo doc`, kept as an alias. |
-| `ekwo post <document>` | Books it, through `post_document()`. `--dry-run` shows the entry the database would write and writes nothing. |
+| `ekwo doc approve <document>` | Approves a draft, as it stands, for an agent to post where agents post in `review`, through `approve_document()`. Signed in as yourself, with `documents.post`; refused to a machine key. A change to the draft afterwards needs another approval. |
+| `ekwo company agent-posting [review\|autopilot\|review_only]` | The setting `agent_posting`: how an agent — a machine key, the MCP server — books a document of the company in use. `review`, the default, once a person approved it, unless the agent's session was started with `--autopilot`; `autopilot`, directly, within its rights, each posting on the audit trail; `review_only`, review with autopilot refused to every session. Without a value, says which. Signed in as yourself, with `company.write`; an agent may only make it stricter. |
+| `ekwo key list [--all]` / `ekwo key create <name> --capability <code>… [--expires <timestamp>] [--autopilot]` | The machine keys of the company in use, with what each may do and how it posts; and one more, through `create_api_key()`, its secret shown once. A key posts as the company's `agent_posting` says; `--autopilot` issues one that posts without approvals — with `company.write`, never in a `review_only` company — and the mode is fixed for good: a key wanted in another mode is issued again. Needs `members.manage`. |
+| `ekwo mcp [--autopilot\|--review]` | The MCP server, over stdio, for an agent: the same server as `ekwo-mcp` of [`@ekwo-ai/mcp`](../mcp/README.md), with its flags and its environment (`ekwo mcp --help`). The `@ekwo-ai/mcp` installed beside this CLI, or the one of its release through `npx` — this CLI keeps its one outside dependency. In `.mcp.json`: `"command": "ekwo", "args": ["mcp"]`. |
+| `ekwo post <document>` | Books it, through `post_document()`. `--dry-run` shows the entry the database would write and writes nothing. Signed in as yourself, you post in any mode; with a machine key, the company's `agent_posting` applies, or the key's own autopilot. |
 | `ekwo cancel <document>` | Undoes a posted invoice, and says how. Back to draft, through `unpost_document()`, where its country allows it and nothing about it has left; otherwise through `cancel_document()`: the credit note that names it, posted and matched against it, and the invoice cancelled. `--date` books the credit note on another day than the invoice's, which is how a locked period is stepped over; `--credit` asks for the note where a draft was possible. |
 | `ekwo reverse <entry>` | Undoes a posted entry keyed by hand, through `reverse_entry()`: its mirror, posted and matched against it. By id or by number; `--date` as for `cancel`. |
 | `ekwo line contacts suggest [--line <line>]…` / `ekwo line contact set <line> <contact>` | The open receivable and payable lines that name nobody — open items of books imported line by line — with the contacts each could be, best first: a learned motif, the number of a document of the company quoted in the label, the description or the reference of the entry, the words of a contact's name, and how many contacts the same evidence reached. `set` names one, once, through `set_line_contact()`, and the label is learned for the next time. A contact by name or id. |
@@ -386,6 +390,14 @@ extra tables are reported as information. It also checks row level security on
 every table, pending migrations, memberships of deleted users, companies
 without a bank account, and posted entries that do not balance.
 
+Two checks say where the socle lives, ahead of its move to the schema `ekwo`
+in 0.22.0 ([decision 0090](../../docs/decisions/0090-the-socle-has-its-own-schema.md)):
+`socle_schema` (`ekwo` or `public`, found by the marker `ekwo_schema_version()`)
+and `ekwo_exposed` (whether the Data API serves `ekwo`, read from
+`pgrst.db_schemas` where the database carries it; otherwise the line to set).
+`ekwo migrate` prints the same line: Project Settings → Data API → Exposed
+schemas, add `ekwo`.
+
 Exit code `0` when there is no problem, `1` otherwise — usable as a deployment
 gate.
 
@@ -529,7 +541,7 @@ exactly six fields:
   "organization": "My Organisation",
   "country": "<cc>",
   "edition": "community",
-  "schema_version": "0.20.0",
+  "schema_version": "0.21.0",
   "contact_email": "you@example.com"
 }
 ```

package/dist/assets/expected-objects.json

@@ -1,6 +1,6 @@
 {
-  "schemaVersion": "0.20.0",
-  "migration": "20261023160300",
+  "schemaVersion": "0.21.0",
+  "migration": "20261027073538",
   "socle": {
     "schema": "public",
     "tables": [
@@ -346,6 +346,10 @@
             "name": "name",
             "type": "text"
           },
+          {
+            "name": "posting_mode",
+            "type": "text"
+          },
           {
             "name": "prefix",
             "type": "text"
@@ -889,6 +893,10 @@
             "name": "address_line2",
             "type": "text"
           },
+          {
+            "name": "agent_posting",
+            "type": "text"
+          },
           {
             "name": "archived_at",
             "type": "timestamp with time zone"
@@ -4751,6 +4759,18 @@
         "name": "aged_balance",
         "arguments": "p_company_id uuid, p_at date, p_group text"
       },
+      {
+        "name": "agent_call",
+        "arguments": ""
+      },
+      {
+        "name": "agent_mark",
+        "arguments": "p_name text"
+      },
+      {
+        "name": "agent_posting_mode",
+        "arguments": "p_company_id uuid"
+      },
       {
         "name": "amount_text_format",
         "arguments": "p_rounding money_rounding"
@@ -4775,6 +4795,10 @@
         "name": "api_key_on_company",
         "arguments": "p_company_id uuid"
       },
+      {
+        "name": "approve_document",
+        "arguments": "p_document_id uuid"
+      },
       {
         "name": "archive_company",
         "arguments": "p_company_id uuid"
@@ -4947,6 +4971,10 @@
         "name": "commercial_entity",
         "arguments": "p_contact_id uuid"
       },
+      {
+        "name": "companies_agent_posting_by_a_person",
+        "arguments": ""
+      },
       {
         "name": "companies_creator_is_fixed",
         "arguments": ""
@@ -5081,12 +5109,16 @@
       },
       {
         "name": "create_api_key",
-        "arguments": "p_company_id uuid, p_name text, p_capabilities jsonb, p_expires_at timestamp with time zone"
+        "arguments": "p_company_id uuid, p_name text, p_capabilities jsonb, p_expires_at timestamp with time zone, p_posting_mode text"
       },
       {
         "name": "create_company",
         "arguments": "p_name text, p_country character, p_currency_code character, p_language character, p_chart_code text, p_fiscal_year integer, p_fiscal_year_start date, p_owner_user_id uuid"
       },
+      {
+        "name": "create_document",
+        "arguments": "p_document jsonb, p_lines jsonb"
+      },
       {
         "name": "currency_of_bank_account",
         "arguments": ""
@@ -5203,6 +5235,10 @@
         "name": "document_territory",
         "arguments": "p_document_id uuid, p_party text"
       },
+      {
+        "name": "document_version",
+        "arguments": "p_document_id uuid"
+      },
       {
         "name": "documents_allocate_included_tax",
         "arguments": "p_document_id uuid"
@@ -5223,6 +5259,10 @@
         "name": "documents_match_credit_note_on_posting",
         "arguments": ""
       },
+      {
+        "name": "documents_posting_mode",
+        "arguments": ""
+      },
       {
         "name": "documents_refresh_amount_paid",
         "arguments": "p_document_id uuid"
@@ -5819,6 +5859,10 @@
         "name": "reopen_fiscal_year",
         "arguments": "p_fiscal_year_id uuid"
       },
+      {
+        "name": "replace_document_lines",
+        "arguments": "p_document_id uuid, p_lines jsonb"
+      },
       {
         "name": "resolve_counterpart_account",
         "arguments": "p_company_id uuid, p_contact_id uuid, p_is_sale boolean"
@@ -6844,6 +6888,10 @@
         "table": "bank_transactions",
         "name": "bank_transactions_set_updated_at"
       },
+      {
+        "table": "companies",
+        "name": "companies_agent_posting_by_a_person"
+      },
       {
         "table": "companies",
         "name": "companies_audit"
@@ -7108,6 +7156,10 @@
         "table": "documents",
         "name": "documents_match_credit_note_on_posting"
       },
+      {
+        "table": "documents",
+        "name": "documents_posting_mode"
+      },
       {
         "table": "documents",
         "name": "documents_refresh_payment_state"
@@ -9056,6 +9108,39 @@
             "execute"
           ]
         },
+        {
+          "name": "agent_call",
+          "arguments": "",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
+        {
+          "name": "agent_mark",
+          "arguments": "p_name text",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
+        {
+          "name": "agent_posting_mode",
+          "arguments": "p_company_id uuid",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "amount_text_format",
           "arguments": "p_rounding money_rounding",
@@ -9124,6 +9209,17 @@
             "execute"
           ]
         },
+        {
+          "name": "approve_document",
+          "arguments": "p_document_id uuid",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "archive_company",
           "arguments": "p_company_id uuid",
@@ -9544,6 +9640,14 @@
             "execute"
           ]
         },
+        {
+          "name": "companies_agent_posting_by_a_person",
+          "arguments": "",
+          "trigger": true,
+          "anon": [],
+          "authenticated": [],
+          "service_role": []
+        },
         {
           "name": "companies_creator_is_fixed",
           "arguments": "",
@@ -9854,7 +9958,7 @@
         },
         {
           "name": "create_api_key",
-          "arguments": "p_company_id uuid, p_name text, p_capabilities jsonb, p_expires_at timestamp with time zone",
+          "arguments": "p_company_id uuid, p_name text, p_capabilities jsonb, p_expires_at timestamp with time zone, p_posting_mode text",
           "anon": [],
           "authenticated": [
             "execute"
@@ -9874,6 +9978,17 @@
             "execute"
           ]
         },
+        {
+          "name": "create_document",
+          "arguments": "p_document jsonb, p_lines jsonb",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "currency_of_bank_account",
           "arguments": "",
@@ -10151,6 +10266,17 @@
             "execute"
           ]
         },
+        {
+          "name": "document_version",
+          "arguments": "p_document_id uuid",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "documents_allocate_included_tax",
           "arguments": "p_document_id uuid",
@@ -10194,6 +10320,14 @@
           "authenticated": [],
           "service_role": []
         },
+        {
+          "name": "documents_posting_mode",
+          "arguments": "",
+          "trigger": true,
+          "anon": [],
+          "authenticated": [],
+          "service_role": []
+        },
         {
           "name": "documents_refresh_amount_paid",
           "arguments": "p_document_id uuid",
@@ -11761,6 +11895,17 @@
             "execute"
           ]
         },
+        {
+          "name": "replace_document_lines",
+          "arguments": "p_document_id uuid, p_lines jsonb",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "resolve_counterpart_account",
           "arguments": "p_company_id uuid, p_contact_id uuid, p_is_sale boolean",

package/dist/assets/migrations/20261023160600_a_draft_changes_its_lines_in_one_statement.sql

@@ -0,0 +1,126 @@
+-- Ekwo OS — a draft changes its lines in one statement.
+--
+-- Replacing the lines of a draft was two calls from the client: delete every
+-- line, then insert the new ones. When the database refused the insert — a
+-- discount of 100 % fails `document_lines_discount_range`, an account of
+-- another company fails its foreign key — the delete had already happened,
+-- and the draft was left with no line at all. Creating a document had the
+-- same shape: the header, then its lines, so a refused line left an empty
+-- draft behind.
+--
+-- Two functions make each of those one statement, and so one transaction:
+-- either every line is written, or nothing changed.
+--
+--   replace_document_lines(document, lines)  the lines of a draft, replaced
+--   create_document(document, lines)         a draft and its lines, created
+--
+-- Both are `security invoker`: the caller writes as themselves, and row level
+-- security and the guards of the tables decide exactly as they did for the
+-- two calls. A line is given as the client already wrote it — `name`,
+-- `description`, `product_id`, `unit_code`, `unit_price`, `quantity`,
+-- `discount_percent`, `account_id`, `tax_id`, `attributes` — and is numbered
+-- 10, 20, 30… in the order given. What a line leaves out takes the default of
+-- its column, and a null account is resolved by the trigger that always
+-- resolved it.
+
+create or replace function replace_document_lines(p_document_id uuid, p_lines jsonb)
+returns integer
+language plpgsql
+security invoker
+set search_path = public, pg_temp
+as $$
+declare
+  v_document documents%rowtype;
+  v_count    integer;
+begin
+  if p_lines is null or jsonb_typeof(p_lines) <> 'array' then
+    raise exception 'lines_not_an_array: the lines of a document are a JSON array'
+      using errcode = '22023';
+  end if;
+
+  select * into v_document from documents where id = p_document_id for update;
+  if not found then
+    raise exception 'unknown_document: no document % in the companies you can see', p_document_id
+      using errcode = 'P0002';
+  end if;
+  if v_document.state <> 'draft' then
+    raise exception 'document_not_draft: document % is %. A posted document is not edited; correct it with a credit note.',
+      p_document_id, v_document.state
+      using errcode = '55006';
+  end if;
+
+  delete from document_lines where document_id = p_document_id;
+
+  insert into document_lines (
+    document_id, company_id, sequence, line_type, product_id, name, description,
+    unit_code, unit_price, quantity, discount_percent, account_id, tax_id, attributes
+  )
+  select p_document_id, v_document.company_id, (l.ordinality * 10)::integer,
+         coalesce((l.line ->> 'line_type')::document_line_type, 'product'),
+         (l.line ->> 'product_id')::uuid,
+         l.line ->> 'name',
+         l.line ->> 'description',
+         coalesce(l.line ->> 'unit_code', 'C62'),
+         coalesce((l.line ->> 'unit_price')::numeric, 0),
+         coalesce((l.line ->> 'quantity')::numeric, 1),
+         coalesce((l.line ->> 'discount_percent')::numeric, 0),
+         (l.line ->> 'account_id')::uuid,
+         (l.line ->> 'tax_id')::uuid,
+         coalesce(l.line -> 'attributes', '{}'::jsonb)
+    from jsonb_array_elements(p_lines) with ordinality as l(line, ordinality);
+
+  get diagnostics v_count = row_count;
+  return v_count;
+end;
+$$;
+
+comment on function replace_document_lines(uuid, jsonb) is
+  'Replaces every line of a draft with the lines given, in one statement: when the database refuses one of them, the draft keeps the lines it had. Security invoker, so row level security and the guards of document_lines decide as for a direct write.';
+
+revoke execute on function replace_document_lines(uuid, jsonb) from public, anon;
+grant execute on function replace_document_lines(uuid, jsonb) to authenticated, service_role;
+
+create or replace function create_document(p_document jsonb, p_lines jsonb)
+returns uuid
+language plpgsql
+security invoker
+set search_path = public, pg_temp
+as $$
+declare
+  v_id uuid;
+begin
+  if p_document is null or jsonb_typeof(p_document) <> 'object' then
+    raise exception 'document_not_an_object: the header of a document is a JSON object'
+      using errcode = '22023';
+  end if;
+
+  insert into documents (
+    company_id, doc_type, contact_id, document_date, due_date, accounting_date, number,
+    supplier_reference, currency_code, journal_id, payment_reference, client_ref
+  )
+  values (
+    (p_document ->> 'company_id')::uuid,
+    (p_document ->> 'doc_type')::doc_type,
+    (p_document ->> 'contact_id')::uuid,
+    (p_document ->> 'document_date')::date,
+    (p_document ->> 'due_date')::date,
+    (p_document ->> 'accounting_date')::date,
+    p_document ->> 'number',
+    p_document ->> 'supplier_reference',
+    p_document ->> 'currency_code',
+    (p_document ->> 'journal_id')::uuid,
+    p_document ->> 'payment_reference',
+    p_document ->> 'client_ref'
+  )
+  returning id into v_id;
+
+  perform replace_document_lines(v_id, p_lines);
+  return v_id;
+end;
+$$;
+
+comment on function create_document(jsonb, jsonb) is
+  'Creates a draft and its lines in one statement: a refused line creates nothing, rather than an empty draft. The header names company_id, doc_type, contact_id, document_date and currency_code, and optionally due_date, accounting_date, number, supplier_reference, journal_id, payment_reference and client_ref. Security invoker.';
+
+revoke execute on function create_document(jsonb, jsonb) from public, anon;
+grant execute on function create_document(jsonb, jsonb) to authenticated, service_role;