ekwo-os 0.7.0 → 0.9.0

package/README.md

@@ -65,9 +65,10 @@ either.
    three questions whose wrong answer is expensive: the country, the chart and
    the language.
 
-4. **Sign in** to your project as that administrator and start booking. Until
-   the Community web application lands, the interface is the REST API Supabase
-   generates from the schema, or `psql`, or `@ekwo-ai/core`.
+4. **Sign in** to your project as that administrator and start booking — in
+   the web application, [Ekwo Cloud](https://cloud.ekwo.ai), which opens your
+   own instance, or through the REST API Supabase generates from the schema,
+   `psql` or `@ekwo-ai/core`.
 
 5. **Do the four things below**, while the dashboard is still open. The
    installer prints them at the end of a successful run, because three of them
@@ -323,7 +324,7 @@ instead if the account already exists, and no key is needed.
 | `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 payment record` | Money in or out, booked and matched. With `--doc`, against that document. |
 | `ekwo match <transaction> <document>` | A bank statement line pays a document, through `settle_from_statement()`. |
-| `ekwo import <source> <file>…` | Books kept elsewhere — `trial-balance`, `fec`, `journal-items`, `journal-report` — whole or not at all, through `import_books()`, with a correspondence of accounts and journals you save and give back; or a bank statement — `camt.053`, `coda`, `cfonb120` — as pending lines. `--dry-run` rehearses. See [taking over books](#taking-over-books-ekwo-import). |
+| `ekwo import <source> <file>…` | Books kept elsewhere — `trial-balance`, `fec`, `journal-items`, `journal-report`, `transaction-journal`, `xaf` — whole or not at all, through `import_books()`, with a correspondence of accounts and journals you save and give back; or a bank statement — `camt.053`, `coda`, `cfonb120` — as pending lines. `--dry-run` rehearses. See [taking over books](#taking-over-books-ekwo-import). |
 | `ekwo doc list` / `show` | What exists, and with `--unpaid` what is posted and still owed. See [keeping books](#keeping-books). |
 
 There is no `eject`, because there is nothing to eject from. The schema is in
@@ -338,7 +339,7 @@ place, so the output reads the same in a file or a CI log — and takes `--json`
 for a program.
 
 `ekwo help --json` answers the list of commands and, in `usage`, the whole
-text of `--help` without colour: every flag and variable, for an assistant
+text of `--help` without colour: every flag and variable, for an agent
 that reads one document rather than a terminal.
 
 Under `--json` the standard output is **one JSON document and nothing else**;
@@ -572,6 +573,8 @@ ekwo import fec 123456789FEC20251231.txt --mapping map.json --open-years
 ekwo import trial-balance balance.csv --opening-date 2026-01-01 --dry-run --save-mapping map.json
 ekwo import journal-items items.csv accounts.csv partners.csv --dry-run --save-mapping map.json
 ekwo import journal-report report.csv chart.csv --date-order dmy --dry-run --save-mapping map.json
+ekwo import transaction-journal journal.csv account-list.csv --date-order mdy --dry-run --save-mapping map.json
+ekwo import xaf books.xaf --open-years --dry-run --save-mapping map.json
 ekwo import camt.053 statement.xml                 # or coda, cfonb120: pending lines for `ekwo match`
 ```
 
@@ -581,6 +584,8 @@ ekwo import camt.053 statement.xml                 # or coda, cfonb120: pending
 | `fec` | A *fichier des écritures comptables*: the eighteen columns of the arrêté of 29 July 2013, tab or bar separated |
 | `journal-items` | The lines of every entry exported as CSV from the list view of an ERP whose ledger is a table of lines, with the chart of accounts and the partners exported beside it |
 | `journal-report` | A journal report or a general ledger detail, saved as CSV from a cloud service's spreadsheet export, with its Journal ID and Account Code columns, and the chart and the contacts beside it |
+| `transaction-journal` | A transaction journal, saved as CSV from a spreadsheet export: each transaction a run of rows under one date, type and number, closed by its total; the list of accounts beside it |
+| `xaf` | An XML Audit File Financial, version 3.2 or 4.0: the accounts, the parties, the opening balance — on the day the file gives it — and every transaction of a year, in one file |
 | `camt.053`, `coda`, `cfonb120` | A bank statement: its lines, pending, ready for `ekwo match` |
 
 Each reader is a brick of [`packages/formats/`](../formats/README.md), named

package/dist/assets/expected-objects.json

@@ -1,6 +1,6 @@
 {
-  "schemaVersion": "0.7.0",
-  "migration": "20260922124012",
+  "schemaVersion": "0.9.0",
+  "migration": "20260928100000",
   "socle": {
     "schema": "public",
     "tables": [
@@ -3743,6 +3743,10 @@
         "name": "amount_text_format",
         "arguments": "p_rounding money_rounding"
       },
+      {
+        "name": "api_key_company",
+        "arguments": ""
+      },
       {
         "name": "assert_may_close_year",
         "arguments": ""
@@ -3815,6 +3819,10 @@
         "name": "cancel_document",
         "arguments": "p_document_id uuid, p_date date"
       },
+      {
+        "name": "canonical_json",
+        "arguments": "p_value jsonb"
+      },
       {
         "name": "catch_up_journal_sequence",
         "arguments": "p_journal_id uuid, p_date date, p_number text"
@@ -3931,6 +3939,10 @@
         "name": "declaration_period_start",
         "arguments": "p_period declaration_period, p_day date"
       },
+      {
+        "name": "default_statement_code",
+        "arguments": "p_company_id uuid, p_kind text, p_at date"
+      },
       {
         "name": "disable_module",
         "arguments": "p_company_id uuid, p_code text"
@@ -3999,6 +4011,10 @@
         "name": "ec_sales_list",
         "arguments": "p_company_id uuid, p_from date, p_to date, p_report_code text"
       },
+      {
+        "name": "ekwo_pre_request",
+        "arguments": ""
+      },
       {
         "name": "ekwo_schema_version",
         "arguments": ""
@@ -4095,6 +4111,10 @@
         "name": "financial_statement",
         "arguments": "p_company_id uuid, p_statement_code text, p_from date, p_to date"
       },
+      {
+        "name": "financial_statement_of_kind",
+        "arguments": "p_company_id uuid, p_kind text, p_from date, p_to date"
+      },
       {
         "name": "fiscal_year_at",
         "arguments": "p_company_id uuid, p_date date"
@@ -4151,6 +4171,10 @@
         "name": "install_country_template",
         "arguments": "p_company_id uuid, p_country character, p_language character, p_chart_code text"
       },
+      {
+        "name": "installed_schema_version",
+        "arguments": ""
+      },
       {
         "name": "instance_has_no_admin",
         "arguments": ""
@@ -4183,6 +4207,10 @@
         "name": "is_instance_admin",
         "arguments": ""
       },
+      {
+        "name": "is_known_caller",
+        "arguments": ""
+      },
       {
         "name": "label_for",
         "arguments": "p_name text, p_i18n jsonb, p_languages text[]"
@@ -4315,6 +4343,10 @@
         "name": "prepare_filing",
         "arguments": "p_company_id uuid, p_from date, p_to date, p_report_code text"
       },
+      {
+        "name": "present_api_key",
+        "arguments": "p_secret text"
+      },
       {
         "name": "purge_audit_log",
         "arguments": "p_before date"
@@ -6817,6 +6849,19 @@
             "execute"
           ]
         },
+        {
+          "name": "api_key_company",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "assert_may_close_year",
           "arguments": "",
@@ -6985,6 +7030,17 @@
             "execute"
           ]
         },
+        {
+          "name": "canonical_json",
+          "arguments": "p_value jsonb",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "catch_up_journal_sequence",
           "arguments": "p_journal_id uuid, p_date date, p_number text",
@@ -7281,6 +7337,17 @@
             "execute"
           ]
         },
+        {
+          "name": "default_statement_code",
+          "arguments": "p_company_id uuid, p_kind text, p_at date",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "disable_module",
           "arguments": "p_company_id uuid, p_code text",
@@ -7441,6 +7508,19 @@
             "execute"
           ]
         },
+        {
+          "name": "ekwo_pre_request",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "ekwo_schema_version",
           "arguments": "",
@@ -7684,6 +7764,17 @@
             "execute"
           ]
         },
+        {
+          "name": "financial_statement_of_kind",
+          "arguments": "p_company_id uuid, p_kind text, p_from date, p_to date",
+          "anon": [],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "fiscal_year_at",
           "arguments": "p_company_id uuid, p_date date",
@@ -7834,6 +7925,19 @@
             "execute"
           ]
         },
+        {
+          "name": "installed_schema_version",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "instance_has_no_admin",
           "arguments": "",
@@ -7932,6 +8036,19 @@
             "execute"
           ]
         },
+        {
+          "name": "is_known_caller",
+          "arguments": "",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "label_for",
           "arguments": "p_name text, p_i18n jsonb, p_languages text[]",
@@ -8294,6 +8411,19 @@
             "execute"
           ]
         },
+        {
+          "name": "present_api_key",
+          "arguments": "p_secret text",
+          "anon": [
+            "execute"
+          ],
+          "authenticated": [
+            "execute"
+          ],
+          "service_role": [
+            "execute"
+          ]
+        },
         {
           "name": "purge_audit_log",
           "arguments": "p_before date",

package/dist/assets/migrations/20260922143000_a_version_anybody_signed_in_may_read.sql

@@ -0,0 +1,52 @@
+-- Ekwo OS — the version of the schema, for somebody who is on no company yet.
+--
+-- A client of this schema has one question to ask before it draws anything:
+-- is this installation new enough for the code I ship? The answer is
+-- `instance.schema_version`, and the policy on that table admits members of
+-- at least one company and instance administrators — for the reason written
+-- in `20260911140000`: self sign-up is on by default on a Supabase project,
+-- so a signed-in stranger is ordinary and the organisation's name, its country
+-- and the day it was installed are not theirs to read.
+--
+-- A freshly created account is exactly that stranger. It signs in, reads no
+-- row, and the client cannot tell an instance behind its schema from one
+-- whose row it was never allowed to see. Both are silence, and the two call
+-- for opposite behaviour: print `ekwo migrate`, or say nothing and carry on.
+-- A web application meets this on its first screen, with an account whose
+-- invitation has not arrived yet.
+--
+-- So the version leaves the table and becomes a question of its own.
+-- `installed_schema_version()` is definer — it reads the singleton row past a
+-- policy that was written about the rest of it — and it returns two fields
+-- and no others: the version the migrations wrote, and the edition, which is
+-- `community` or `cloud` and gates nothing anywhere in this repository.
+-- Whoever the caller is, what they learn is what release this software is at.
+-- Nothing about the customer comes with it.
+--
+-- **`anon` does not get it**, and the exception is not worth making. Decision
+-- 0002 keeps the anonymous surface closed, and the list of what `anon` may
+-- execute is the policy helpers, which answer about `auth.uid()` and therefore
+-- say nothing, plus `shared_document()`, which somebody was handed a link to.
+-- The version is not in that shape: nobody asks it before signing in — the
+-- client asks it *after*, which is the moment the old answer went missing —
+-- and granting it would hand an unauthenticated scanner the exact release an
+-- installation runs, for a convenience nothing needs. A reader who needs it
+-- signs in first.
+
+create or replace function installed_schema_version()
+returns table (schema_version text, edition text)
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select i.schema_version, i.edition::text from instance i where i.id = 1;
+$$;
+
+comment on function installed_schema_version() is
+  'The schema version this installation runs, and its edition. Definer, so a signed-in account that is on no company yet can still tell an instance behind its schema from one it may not read the row of — which is the same silence otherwise. Nothing else of the instance row comes with it.';
+
+revoke execute on all functions in schema public from public;
+
+revoke execute on function installed_schema_version() from public, anon;
+grant execute on function installed_schema_version() to authenticated, service_role;

package/dist/assets/migrations/20260922144500_a_balance_sheet_without_knowing_the_pack.sql

@@ -0,0 +1,117 @@
+-- Ekwo OS — asking for a balance sheet without knowing which pack answers.
+--
+-- `financial_statement()` takes `p_statement_code`, and a code belongs to a
+-- country pack: `BE-BNB-ABBR-BS`, `FR-2050`, the generic `IFRS-SME-BS`. A
+-- client that knows which company it is looking at does not know that string,
+-- and it must not learn it — writing `FR-2050` into an application is writing
+-- a country into code, one screen at a time, which is the thing
+-- `docs/decisions/0025` exists to stop.
+--
+-- `available_statements(company, at)` has been the way out since the day the
+-- statements landed: it gives every scheme that company may ask for, with its
+-- kind and whether its chart declares it. What was missing is the step after
+-- it — going from *a balance sheet* to the one statement that answers, and
+-- doing it the same way twice. Every caller that wanted one wrote its own
+-- choice: take the first row, prefer `is_default`, prefer the country over the
+-- generic. Three readers, three orders, and the day a pack carries two balance
+-- sheets they disagree about which is the company's.
+--
+-- Two functions, and no new rule about accounting:
+--
+--   `default_statement_code(company, kind, at)` — the one scheme of that kind
+--       this company reports on. The order is the pack's own preferences,
+--       stated once: a statement the company's chart declares
+--       (`chart_templates.statements`, which is what `is_default` marks) comes
+--       first; then one of the company's country, because a national scheme is
+--       what an administration reads; then the generic framework, which fits
+--       any chart and is the fallback and never the first answer. `code`
+--       settles a tie, so the answer does not depend on the order rows were
+--       loaded in.
+--
+--   `financial_statement_of_kind(company, kind, from, to)` — the same table
+--       `financial_statement()` returns, resolved that way, with the code it
+--       chose in the first column. The code comes back because a reader has to
+--       be able to say which scheme it is printing, and because the next call
+--       — `unmapped_accounts()`, an XBRL export — takes the code.
+--
+-- The kind is the one the schema already has: `balance_sheet`,
+-- `income_statement`, `allocation`, `cash_flow` — the vocabulary of
+-- `statement_templates.kind`, not a new one. A company with no statement of
+-- the kind asked for is told so, and told what it does have; a company that
+-- installed no pack at all has the generic framework and so has both of the
+-- two that are produced.
+--
+-- The date the validity is read at is `p_to`: a statement is the one that was
+-- in force at the end of the period being reported, not the one in force
+-- today. A scheme replaced last month still prints last year.
+
+create or replace function default_statement_code(
+  p_company_id uuid,
+  p_kind       text,
+  p_at         date default null
+)
+returns text
+language sql
+stable
+as $$
+  select s.code
+    from available_statements(p_company_id, p_at) s
+   where s.kind = p_kind
+   order by s.is_default desc, (s.country is null), s.code
+   limit 1;
+$$;
+
+comment on function default_statement_code(uuid, text, date) is
+  'The statement of a kind this company reports on: one its chart declares, else one of its country, else the generic framework. Null when it has none of that kind. The one place that choice is made, so two readers cannot disagree about which balance sheet is the company''s.';
+
+create or replace function financial_statement_of_kind(
+  p_company_id uuid,
+  p_kind       text,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  statement_code text,
+  line_code      text,
+  parent_code    text,
+  name           text,
+  sequence       integer,
+  is_total       boolean,
+  amount         numeric,
+  xbrl_element   text
+)
+language plpgsql
+stable
+as $$
+declare
+  v_code  text;
+  v_kinds text;
+begin
+  if not exists (select 1 from companies c where c.id = p_company_id) then
+    raise exception 'unknown_company: %', p_company_id;
+  end if;
+
+  v_code := default_statement_code(p_company_id, p_kind, p_to);
+  if v_code is null then
+    select string_agg(distinct s.kind, ', ' order by s.kind) into v_kinds
+      from available_statements(p_company_id, p_to) s;
+    raise exception 'unknown_statement: this company reports no % — it reports %. available_statements() names each one by code.',
+      p_kind, coalesce(v_kinds, 'nothing');
+  end if;
+
+  return query
+    select v_code, f.line_code, f.parent_code, f.name, f.sequence,
+           f.is_total, f.amount, f.xbrl_element
+      from financial_statement(p_company_id, v_code, p_from, p_to) f;
+end;
+$$;
+
+comment on function financial_statement_of_kind(uuid, text, date, date) is
+  'One financial statement of a company by kind — balance_sheet, income_statement, allocation, cash_flow — for a caller that does not know which scheme its country pack carries. Resolves through default_statement_code() at the end date of the period, then answers as financial_statement() does, with the code it chose in the first column.';
+
+revoke execute on all functions in schema public from public;
+
+revoke execute on function default_statement_code(uuid, text, date) from public, anon;
+grant execute on function default_statement_code(uuid, text, date) to authenticated, service_role;
+revoke execute on function financial_statement_of_kind(uuid, text, date, date) from public, anon;
+grant execute on function financial_statement_of_kind(uuid, text, date, date) to authenticated, service_role;