ekwo-os 0.23.0 → 0.24.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
@@ -541,7 +541,7 @@ exactly six fields:
541
541
  "organization": "My Organisation",
542
542
  "country": "<cc>",
543
543
  "edition": "community",
544
- "schema_version": "0.23.0",
544
+ "schema_version": "0.24.0",
545
545
  "contact_email": "you@example.com"
546
546
  }
547
547
  ```
@@ -1,6 +1,6 @@
1
1
  {
2
- "schemaVersion": "0.23.0",
3
- "migration": "20261028070000",
2
+ "schemaVersion": "0.24.0",
3
+ "migration": "20261028160000",
4
4
  "socle": {
5
5
  "schema": "ekwo",
6
6
  "tables": [
@@ -5259,6 +5259,10 @@
5259
5259
  "name": "documents_match_credit_note_on_posting",
5260
5260
  "arguments": ""
5261
5261
  },
5262
+ {
5263
+ "name": "documents_need_a_contact",
5264
+ "arguments": ""
5265
+ },
5262
5266
  {
5263
5267
  "name": "documents_posting_mode",
5264
5268
  "arguments": ""
@@ -5791,6 +5795,10 @@
5791
5795
  "name": "purge_audit_log",
5792
5796
  "arguments": "p_before date"
5793
5797
  },
5798
+ {
5799
+ "name": "receive_purchase_document",
5800
+ "arguments": "p_company_id uuid, p_reference text, p_taken_at timestamp with time zone, p_files jsonb"
5801
+ },
5794
5802
  {
5795
5803
  "name": "reconcile",
5796
5804
  "arguments": "p_line_a uuid, p_line_b uuid, p_amount numeric"
@@ -5963,6 +5971,10 @@
5963
5971
  "name": "statement_rule_catches",
5964
5972
  "arguments": "p_rule statement_line_rules, p_code text, p_account_type account_type, p_balance numeric"
5965
5973
  },
5974
+ {
5975
+ "name": "storage_path_company",
5976
+ "arguments": "p_name text"
5977
+ },
5966
5978
  {
5967
5979
  "name": "suggest_combination",
5968
5980
  "arguments": "p_transaction_id uuid"
@@ -7140,6 +7152,10 @@
7140
7152
  "table": "documents",
7141
7153
  "name": "documents_contact_id_not_merged"
7142
7154
  },
7155
+ {
7156
+ "table": "documents",
7157
+ "name": "documents_contact_named"
7158
+ },
7143
7159
  {
7144
7160
  "table": "documents",
7145
7161
  "name": "documents_currency_of_company"
@@ -10324,6 +10340,14 @@
10324
10340
  "authenticated": [],
10325
10341
  "service_role": []
10326
10342
  },
10343
+ {
10344
+ "name": "documents_need_a_contact",
10345
+ "arguments": "",
10346
+ "trigger": true,
10347
+ "anon": [],
10348
+ "authenticated": [],
10349
+ "service_role": []
10350
+ },
10327
10351
  {
10328
10352
  "name": "documents_posting_mode",
10329
10353
  "arguments": "",
@@ -11727,6 +11751,17 @@
11727
11751
  "execute"
11728
11752
  ]
11729
11753
  },
11754
+ {
11755
+ "name": "receive_purchase_document",
11756
+ "arguments": "p_company_id uuid, p_reference text, p_taken_at timestamp with time zone, p_files jsonb",
11757
+ "anon": [],
11758
+ "authenticated": [
11759
+ "execute"
11760
+ ],
11761
+ "service_role": [
11762
+ "execute"
11763
+ ]
11764
+ },
11730
11765
  {
11731
11766
  "name": "reconcile",
11732
11767
  "arguments": "p_line_a uuid, p_line_b uuid, p_amount numeric",
@@ -12176,6 +12211,17 @@
12176
12211
  "execute"
12177
12212
  ]
12178
12213
  },
12214
+ {
12215
+ "name": "storage_path_company",
12216
+ "arguments": "p_name text",
12217
+ "anon": [],
12218
+ "authenticated": [
12219
+ "execute"
12220
+ ],
12221
+ "service_role": [
12222
+ "execute"
12223
+ ]
12224
+ },
12179
12225
  {
12180
12226
  "name": "suggest_combination",
12181
12227
  "arguments": "p_transaction_id uuid",
@@ -0,0 +1,284 @@
1
+ -- Ekwo OS — a purchase document sent from a phone arrives as a draft purchase
2
+ -- (decision 0091).
3
+ --
4
+ -- A phone photographs a receipt or an invoice and sends it to the purchase
5
+ -- inbox of a company. The pages go to the installation's private Storage
6
+ -- bucket `attachments`, with the person's own session, under
7
+ -- `<company_id>/inbox/<reference>/`; then one call announces them:
8
+ --
9
+ -- receive_purchase_document(company, reference, taken_at, files)
10
+ --
11
+ -- which writes what the books already have a place for. **One draft
12
+ -- purchase** in `documents` — `purchase_invoice`, `client_ref` the reference
13
+ -- the phone gave it, dated the day it was taken, in the company's currency,
14
+ -- with no line and so no amount — and **one `attachments` row per page** on
15
+ -- that document, in the order the phone sent them. No new table. Whoever
16
+ -- reads the inbox finds the draft, reads its pages and turns it into the
17
+ -- purchase the person posts.
18
+ --
19
+ -- **The supplier is not known yet.** Nothing has read the pages when the
20
+ -- phone sends them, so the draft names no contact: `documents.contact_id`
21
+ -- becomes nullable **on a draft only**. A document that leaves draft names its
22
+ -- contact — `documents_need_a_contact()` refuses it by name before the check
23
+ -- `documents_contact_unless_draft` would, so `post_document()` and everything
24
+ -- after it still meet a document with a contact, as they always have. A draft
25
+ -- without a contact is, by construction, a document a phone sent and nobody
26
+ -- has read yet: that is how the inbox finds them.
27
+ --
28
+ -- **The rights are the socle's own.** The function is security invoker: the
29
+ -- draft and its pages are written under the row level security of
30
+ -- `documents` and `attachments`, and the caller is asked `documents.write`
31
+ -- first, refused `42501` by name — the capability every draft is written
32
+ -- with, for a person or a machine key alike.
33
+ --
34
+ -- **The paths are checked, not trusted.** Every `storage_path` is under
35
+ -- `<company_id>/inbox/<reference>/`, names a file rather than a folder, and
36
+ -- carries no `..`; every type is an image or a PDF; where the installation
37
+ -- has Supabase Storage, every path is an object of the bucket. Each refusal
38
+ -- has its name.
39
+ --
40
+ -- **Twice is once.** The reference is the idempotency key the socle already
41
+ -- has, `documents.client_ref`, unique per company: a second call with the
42
+ -- same reference returns the same document and adds only the pages it does
43
+ -- not hold yet, by path. A reference another kind of document already
44
+ -- carries is refused, never reused.
45
+ --
46
+ -- **Storage.** No migration of the socle created the bucket a company's files
47
+ -- are kept in, nor said who may write there. Where the installation has
48
+ -- Supabase Storage, this file creates the private bucket `attachments` when it
49
+ -- is missing and adds three policies on `storage.objects`, permissive like
50
+ -- any other, beside whatever an operator wrote by hand: the first folder of a
51
+ -- path is the company, and a person reads there with `documents.read` or
52
+ -- `filings.read`, writes and removes there with `documents.write` or
53
+ -- `filings.write` — the capabilities of the `attachments` rows that name
54
+ -- those files. That covers the inbox of the phone and the
55
+ -- `<company_id>/document/…` the web application already writes. A database
56
+ -- without Storage, or a role that may not alter it, skips this part with a
57
+ -- notice; `ekwo doctor` does not depend on it.
58
+
59
+ -- ---------------------------------------------------------------------------
60
+ -- 1. A draft may wait for its contact
61
+ -- ---------------------------------------------------------------------------
62
+
63
+ alter table documents alter column contact_id drop not null;
64
+
65
+ alter table documents drop constraint if exists documents_contact_unless_draft;
66
+ alter table documents add constraint documents_contact_unless_draft
67
+ check (state = 'draft' or contact_id is not null);
68
+
69
+ comment on column documents.contact_id is
70
+ 'The customer of a sale, the supplier of a purchase. Null only on a draft nobody has read yet — a purchase document sent from a phone (receive_purchase_document()) — and named before the document leaves draft (documents_need_a_contact()).';
71
+
72
+ create or replace function documents_need_a_contact()
73
+ returns trigger
74
+ language plpgsql
75
+ set search_path = ekwo, pg_temp
76
+ as $$
77
+ begin
78
+ if new.state <> 'draft' and new.contact_id is null then
79
+ raise exception 'document_without_contact: % names no contact yet. Name its supplier or its customer on the draft, then post it.',
80
+ coalesce(new.supplier_reference, new.client_ref, new.id::text)
81
+ using errcode = '23514';
82
+ end if;
83
+ return new;
84
+ end;
85
+ $$;
86
+
87
+ comment on function documents_need_a_contact() is
88
+ 'Refuses document_without_contact for a document that leaves draft, or is written in another state, without a contact. A draft may wait for its contact; nothing after it does.';
89
+
90
+ revoke execute on function documents_need_a_contact() from public, anon, authenticated, service_role;
91
+
92
+ -- Named to fire before the other row triggers of documents, which run in
93
+ -- the order of their names: the missing contact is the first thing said.
94
+ drop trigger if exists documents_contact_named on documents;
95
+ create trigger documents_contact_named
96
+ before insert or update of state, contact_id on documents
97
+ for each row execute function documents_need_a_contact();
98
+
99
+ -- ---------------------------------------------------------------------------
100
+ -- 2. receive_purchase_document()
101
+ -- ---------------------------------------------------------------------------
102
+
103
+ create or replace function receive_purchase_document(
104
+ p_company_id uuid,
105
+ p_reference text,
106
+ p_taken_at timestamptz,
107
+ p_files jsonb
108
+ )
109
+ returns uuid
110
+ language plpgsql
111
+ security invoker
112
+ set search_path = ekwo, pg_temp
113
+ as $$
114
+ declare
115
+ v_folder text;
116
+ v_document documents;
117
+ v_currency char(3);
118
+ v_zone text;
119
+ v_file record;
120
+ v_path text;
121
+ v_type text;
122
+ v_name text;
123
+ v_size bigint;
124
+ v_found boolean;
125
+ begin
126
+ if p_company_id is null or not may_know_of_company(p_company_id) then
127
+ raise exception 'unknown_company: %', p_company_id using errcode = 'no_data_found';
128
+ end if;
129
+ if not has_capability(p_company_id, 'documents.write') then
130
+ raise exception 'not_allowed: adding a purchase to this company needs documents.write'
131
+ using errcode = '42501';
132
+ end if;
133
+
134
+ if p_reference is null or p_reference <> btrim(p_reference) or length(p_reference) not between 1 and 200
135
+ or p_reference ~ '[/\\]' or p_reference in ('.', '..') then
136
+ raise exception 'inbox_reference_invalid: the reference of a document sent to the inbox is one to 200 characters, without a slash or surrounding spaces'
137
+ using errcode = '22023';
138
+ end if;
139
+ if p_files is null or jsonb_typeof(p_files) <> 'array' or jsonb_array_length(p_files) = 0 then
140
+ raise exception 'inbox_no_files: a document sent to the inbox carries at least one page, as a JSON array of {storage_path, file_name, mime_type, byte_size}'
141
+ using errcode = '22023';
142
+ end if;
143
+
144
+ -- Every page is checked before anything is written.
145
+ v_folder := p_company_id::text || '/inbox/' || p_reference || '/';
146
+ for v_file in select value as page, ordinality as n from jsonb_array_elements(p_files) with ordinality loop
147
+ if jsonb_typeof(v_file.page) <> 'object' then
148
+ raise exception 'inbox_no_files: page % is not a JSON object', v_file.n using errcode = '22023';
149
+ end if;
150
+ v_path := v_file.page ->> 'storage_path';
151
+ if v_path is null or left(v_path, length(v_folder)) <> v_folder or length(v_path) = length(v_folder)
152
+ or right(v_path, 1) = '/' or v_path like '%/../%' or v_path like '%/./%' or v_path ~ '//' then
153
+ raise exception 'inbox_path_outside: page % is stored at %, which is not a file under %', v_file.n, coalesce(v_path, 'no path'), v_folder
154
+ using errcode = '22023';
155
+ end if;
156
+ v_type := lower(coalesce(v_file.page ->> 'mime_type', ''));
157
+ if v_type !~ '^image/[a-z0-9][a-z0-9.+-]*$' and v_type <> 'application/pdf' then
158
+ raise exception 'inbox_file_type: page % is %, and the inbox takes images and PDF', v_file.n, coalesce(nullif(v_type, ''), 'of no type')
159
+ using errcode = '22023';
160
+ end if;
161
+ if v_file.page ? 'byte_size' and jsonb_typeof(v_file.page -> 'byte_size') <> 'null'
162
+ and (jsonb_typeof(v_file.page -> 'byte_size') <> 'number' or (v_file.page ->> 'byte_size')::numeric < 0
163
+ or (v_file.page ->> 'byte_size')::numeric <> trunc((v_file.page ->> 'byte_size')::numeric)) then
164
+ raise exception 'inbox_no_files: page % gives a byte_size that is not a whole number of bytes', v_file.n
165
+ using errcode = '22023';
166
+ end if;
167
+ -- Where the installation has Supabase Storage, the page is there.
168
+ if to_regclass('storage.objects') is not null then
169
+ execute 'select exists (select 1 from storage.objects where bucket_id = $1 and name = $2)'
170
+ into v_found using 'attachments', v_path;
171
+ if not v_found then
172
+ raise exception 'inbox_file_missing: page % is not in the bucket attachments at %. Upload it first, then announce it.', v_file.n, v_path
173
+ using errcode = 'no_data_found';
174
+ end if;
175
+ end if;
176
+ end loop;
177
+
178
+ select * into v_document from documents
179
+ where company_id = p_company_id and client_ref = p_reference;
180
+
181
+ if found and v_document.doc_type not in ('purchase_invoice', 'purchase_credit_note') then
182
+ raise exception 'inbox_reference_taken: the reference % already names another kind of document in this company', p_reference
183
+ using errcode = '23505';
184
+ end if;
185
+
186
+ if not found then
187
+ select c.currency_code into v_currency from companies c where c.id = p_company_id;
188
+ -- The day it was taken, where the person is: their own time zone when
189
+ -- they set one, else the day of the instant as it was sent.
190
+ select p.timezone into v_zone from user_preferences p
191
+ where p.user_id = auth.uid() and p.timezone in (select name from pg_timezone_names);
192
+ insert into documents (company_id, doc_type, contact_id, document_date, currency_code, client_ref)
193
+ values (p_company_id, 'purchase_invoice', null,
194
+ (coalesce(p_taken_at, now()) at time zone coalesce(v_zone, 'UTC'))::date,
195
+ v_currency, p_reference)
196
+ returning * into v_document;
197
+ end if;
198
+
199
+ -- The pages it does not hold yet, in the order they were sent.
200
+ for v_file in select value as page, ordinality as n from jsonb_array_elements(p_files) with ordinality loop
201
+ v_path := v_file.page ->> 'storage_path';
202
+ continue when exists (select 1 from attachments a
203
+ where a.entity_type = 'document' and a.entity_id = v_document.id
204
+ and a.storage_path = v_path);
205
+ v_name := nullif(btrim(coalesce(v_file.page ->> 'file_name', '')), '');
206
+ v_size := case when jsonb_typeof(v_file.page -> 'byte_size') = 'number' then (v_file.page ->> 'byte_size')::bigint end;
207
+ insert into attachments (company_id, entity_type, entity_id, file_name, mime_type, byte_size, storage_path, created_at)
208
+ values (p_company_id, 'document', v_document.id,
209
+ coalesce(v_name, regexp_replace(v_path, '^.*/', '')),
210
+ lower(v_file.page ->> 'mime_type'), v_size, v_path, clock_timestamp());
211
+ end loop;
212
+
213
+ return v_document.id;
214
+ end;
215
+ $$;
216
+
217
+ comment on function receive_purchase_document(uuid, text, timestamptz, jsonb) is
218
+ 'A purchase document sent from a phone to the inbox of a company: one draft purchase_invoice, client_ref the reference the phone gave it, dated the day it was taken (the caller''s time zone when they set one), in the company''s currency, with no contact and no line yet, and one attachments row per page on it, in the order given. p_files is [{storage_path, file_name, mime_type, byte_size}]; every path is a file under <company_id>/inbox/<reference>/ of the bucket attachments, and an object there where the installation has Storage (inbox_path_outside, inbox_file_missing); every type an image or a PDF (inbox_file_type). Needs documents.write (not_allowed, 42501). Idempotent on (company, reference): a second call returns the same document and adds only the pages it does not hold, by path. Security invoker. Decision 0091.';
219
+
220
+ revoke execute on function receive_purchase_document(uuid, text, timestamptz, jsonb) from public, anon;
221
+ grant execute on function receive_purchase_document(uuid, text, timestamptz, jsonb) to authenticated, service_role;
222
+
223
+ -- ---------------------------------------------------------------------------
224
+ -- 3. The bucket a company's files are kept in, and who may write there
225
+ -- ---------------------------------------------------------------------------
226
+
227
+ create or replace function storage_path_company(p_name text)
228
+ returns uuid
229
+ language sql
230
+ immutable
231
+ set search_path = ekwo, pg_temp
232
+ as $$
233
+ select case
234
+ when split_part(p_name, '/', 1) ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
235
+ then split_part(p_name, '/', 1)::uuid
236
+ end;
237
+ $$;
238
+
239
+ comment on function storage_path_company(text) is
240
+ 'The company a file of the bucket attachments belongs to: the first folder of its path when it is a company id, else null. Read by the policies of storage.objects on that bucket.';
241
+
242
+ revoke execute on function storage_path_company(text) from public, anon;
243
+ grant execute on function storage_path_company(text) to authenticated, service_role;
244
+
245
+ do $$
246
+ begin
247
+ if to_regclass('storage.objects') is null or to_regclass('storage.buckets') is null then
248
+ raise notice 'ekwo: no Supabase Storage in this database; the bucket attachments and its policies are left to the installation.';
249
+ return;
250
+ end if;
251
+
252
+ insert into storage.buckets (id, name, public) values ('attachments', 'attachments', false)
253
+ on conflict (id) do nothing;
254
+
255
+ drop policy if exists ekwo_attachments_read on storage.objects;
256
+ create policy ekwo_attachments_read on storage.objects
257
+ for select to authenticated
258
+ using (bucket_id = 'attachments'
259
+ and (ekwo.has_capability(ekwo.storage_path_company(name), 'documents.read')
260
+ or ekwo.has_capability(ekwo.storage_path_company(name), 'filings.read')));
261
+
262
+ drop policy if exists ekwo_attachments_write on storage.objects;
263
+ create policy ekwo_attachments_write on storage.objects
264
+ for insert to authenticated
265
+ with check (bucket_id = 'attachments'
266
+ and (ekwo.has_capability(ekwo.storage_path_company(name), 'documents.write')
267
+ or ekwo.has_capability(ekwo.storage_path_company(name), 'filings.write')));
268
+
269
+ drop policy if exists ekwo_attachments_remove on storage.objects;
270
+ create policy ekwo_attachments_remove on storage.objects
271
+ for delete to authenticated
272
+ using (bucket_id = 'attachments'
273
+ and (ekwo.has_capability(ekwo.storage_path_company(name), 'documents.write')
274
+ or ekwo.has_capability(ekwo.storage_path_company(name), 'filings.write')));
275
+ exception
276
+ when insufficient_privilege then
277
+ raise notice 'ekwo: could not create the bucket attachments or its policies on storage.objects (%). Somebody with the privilege runs this file''s third part again; until then a phone cannot upload to the inbox.', sqlerrm;
278
+ end $$;
279
+
280
+ -- `create or replace` keeps the privileges the function already had, and the
281
+ -- revoke is what every file of this directory ends with.
282
+ revoke execute on all functions in schema ekwo from public;
283
+
284
+ notify pgrst, 'reload schema';
@@ -0,0 +1,33 @@
1
+ -- Ekwo OS — the schema this release defines is 0.24.0.
2
+ --
3
+ -- `ekwo_schema_version()` is the one place the number lives, and a migration
4
+ -- is the only thing that moves it. A database then answers for the files it
5
+ -- has actually run rather than for what somebody believed it had run: the
6
+ -- column default and `init_instance()` both call this function, so a fresh
7
+ -- install records the new number without a second edit, and `ekwo migrate`
8
+ -- reads it back onto `instance.schema_version` for a database that was
9
+ -- installed at an older one.
10
+ --
11
+ -- Between 0.23.0 and here a document sent from a phone became a draft
12
+ -- purchase (`20261028152338_a_purchase_arrives_from_the_phone`, decision
13
+ -- 0091): one function, one draft-only nullable column and, where Storage is
14
+ -- present, a bucket and its policies — all additive.
15
+ --
16
+ -- The floor of `ekwo-os`, `@ekwo-ai/core` and `@ekwo-ai/mcp` stays at 0.19.0:
17
+ -- the packages read and call nothing the release added.
18
+
19
+ create or replace function ekwo_schema_version()
20
+ returns text
21
+ language sql
22
+ immutable
23
+ as $$
24
+ select '0.24.0'::text;
25
+ $$;
26
+
27
+ comment on function ekwo_schema_version() is
28
+ 'Schema version of the installed release. Bumped by a migration, never by hand.';
29
+
30
+ -- `create or replace` keeps the privileges the function already had, and the
31
+ -- revoke is what every file of this directory ends with.
32
+ revoke execute on all functions in schema ekwo from public;
33
+ grant execute on function ekwo_schema_version() to authenticated, service_role;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ekwo-os",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "description": "Install and operate Ekwo OS on your own Supabase project: npx ekwo-os init.",
5
5
  "keywords": [
6
6
  "accounting",
@@ -50,7 +50,7 @@
50
50
  "typecheck": "tsc -p tsconfig.json --noEmit"
51
51
  },
52
52
  "dependencies": {
53
- "@ekwo-ai/core": "^0.23.0",
53
+ "@ekwo-ai/core": "^0.24.0",
54
54
  "postgres": "^3.4.5"
55
55
  }
56
56
  }