@zeyos/client 0.3.0 → 0.4.0

package/okf/entities/transactions.md

@@ -0,0 +1,118 @@
+---
+type: ZeyOS Entity
+title: Transactions
+description: Billing, procurement, or production business transactions.
+resource: zeyos://api/transactions
+tags: [billing, generated]
+api_backed: true
+list_operation: listTransactions
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `fork` | integer | yes | — | yes | [forks](/entities/forks.md) |
+| `ownergroup` | integer | yes | — | yes | [groups](/entities/groups.md) |
+| `creator` | integer | yes | — | — | — |
+| `assigneduser` | integer | yes | — | yes | [users](/entities/users.md) |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `account` | integer | yes | — | yes | [accounts](/entities/accounts.md) |
+| `item` | integer | yes | — | yes | [items](/entities/items.md) |
+| `contract` | integer | yes | — | yes | [contracts](/entities/contracts.md) |
+| `transactionnum` | text | no | — | yes | — |
+| `type` | smallint | no | `0` | yes | — |
+| `date` | bigint | no | `date_part('epoch', now())` | yes | — |
+| `duedate` | bigint | yes | — | — | — |
+| `status` | smallint | no | `0` | — | — |
+| `calculation` | smallint | no | `0` | — | — |
+| `productionfactor` | integer | yes | — | — | — |
+| `currency` | character varying(3) | no | — | — | — |
+| `exchangerate` | double precision | no | `1` | — | — |
+| `taxid` | text | no | `''` | — | — |
+| `shippingrecipient` | text | no | `''` | — | — |
+| `shippingaddress` | text | no | `''` | — | — |
+| `shippingpostalcode` | text | no | `''` | — | — |
+| `shippingcity` | text | no | `''` | — | — |
+| `shippingregion` | text | no | `''` | — | — |
+| `shippingcountry` | character varying(2) | no | `''` | — | — |
+| `billingrecipient` | text | no | `''` | — | — |
+| `billingaddress` | text | no | `''` | — | — |
+| `billingpostalcode` | text | no | `''` | — | — |
+| `billingcity` | text | no | `''` | — | — |
+| `billingregion` | text | no | `''` | — | — |
+| `billingcountry` | character varying(2) | no | `''` | — | — |
+| `sellertaxid` | text | no | `''` | — | — |
+| `sellername` | text | no | `''` | — | — |
+| `selleraddress` | text | no | `''` | — | — |
+| `sellerpostalcode` | text | no | `''` | — | — |
+| `sellercity` | text | no | `''` | — | — |
+| `sellerregion` | text | no | `''` | — | — |
+| `sellercountry` | character varying(2) | no | `''` | — | — |
+| `discount` | double precision | no | `0` | — | — |
+| `netamount` | double precision | no | `0` | — | — |
+| `tax` | double precision | no | `0` | — | — |
+| `margin` | double precision | no | `0` | — | — |
+| `weight` | double precision | no | `0` | — | — |
+| `items` | json | yes | — | — | — |
+
+# Foreign Keys
+
+- `fork` → [forks](/entities/forks.md) (`forks.ID`)
+- `ownergroup` → [groups](/entities/groups.md) (`groups.ID`)
+- `assigneduser` → [users](/entities/users.md) (`users.ID`)
+- `account` → [accounts](/entities/accounts.md) (`accounts.ID`)
+- `item` → [items](/entities/items.md) (`items.ID`)
+- `contract` → [contracts](/entities/contracts.md) (`contracts.ID`)
+
+# Enums
+
+### `type`
+
+`0` = BILLING_QUOTE · `1` = BILLING_ORDER · `2` = BILLING_DELIVERY · `3` = BILLING_INVOICE · `4` = BILLING_CREDIT · `5` = PROCUREMENT_REQUEST · `6` = PROCUREMENT_ORDER · `7` = PROCUREMENT_DELIVERY · `8` = PROCUREMENT_INVOICE · `9` = PROCUREMENT_CREDIT · `10` = PRODUCTION_FABRICATION · `11` = PRODUCTION_DISASSEMBLY
+
+### `status`
+
+`0` = DRAFT · `1` = BOOKED · `2` = HOLD · `3` = CANCELLED · `4` = CLOSED · `5` = PARTLYORDERED · `6` = PARTLYORDERED_CANCELLED · `7` = PARTLYORDERED_CLOSED · `8` = ORDERED · `9` = PARTLYDELIVERED · `10` = PARTLYDELIVERED_CANCELLED · `11` = PARTLYDELIVERED_CLOSED · `12` = DELIVERED · `13` = PARTLYINVOICED · `14` = PARTLYINVOICED_CANCELLED · `15` = PARTLYINVOICED_CLOSED · `16` = INVOICED · `17` = PARTLYPAID · `18` = PARTLYPAID_CANCELLED · `19` = PARTLYPAID_CLOSED · `20` = PAID · `21` = OVERPAID · `22` = PROCESSED · `23` = PROCESSED_CANCELLED
+
+### `calculation`
+
+`0` = NET · `1` = GROSS · `2` = EXACT · `3` = LEGACY · `4` = EXTERNAL
+
+# Indexes
+
+- `fk_transactions_account` — btree, partial on `account`
+- `fk_transactions_assigneduser` — gin, partial on `assigneduser`
+- `fk_transactions_contract` — btree, partial on `contract`
+- `fk_transactions_fork` — gin, partial on `fork`
+- `fk_transactions_item` — btree, partial on `item`
+- `fk_transactions_ownergroup` — gin on `ownergroup`
+- `i_transactions_billing_date` — btree, partial on `date`
+- `i_transactions_collection_date` — btree, partial on `date`
+- `i_transactions_nofork` — gin, partial on `fork`
+- `i_transactions_noowner` — gin, partial on `ownergroup`
+- `i_transactions_procurement_date` — btree, partial on `date`
+- `i_transactions_production_date` — btree, partial on `date`
+- `i_transactions_transactionnum` — btree on `transactionnum`
+- `s_transactions_transactionnum` — gin on `transactionnum`
+- `u_transactions_transactionnum_type` — btree, unique, partial on `transactionnum, type`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listTransactions`
+- get: `getTransaction`
+- create: `createTransaction`
+- update: `updateTransaction`
+- delete: `deleteTransaction`
+- exists: `existsTransaction`
+<!-- okf:generated:end -->
+
+# Notes
+
+NO `visibility` column — adding `"visibility":0` to a filter 400s. Use `type` 3=billing invoice, 4=billing credit. Use `netamount` for invoiced revenue; sum client-side (no server-side SUM). Use `date` for period reporting.

package/okf/entities/users.md

@@ -0,0 +1,66 @@
+---
+type: ZeyOS Entity
+title: Users
+description: System users.
+resource: zeyos://api/users
+tags: [platform, generated]
+api_backed: true
+list_operation: listUsers
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `creator` | integer | yes | — | — | — |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `contact` | integer | yes | — | yes | [contacts](/entities/contacts.md) |
+| `activity` | smallint | no | `0` | — | — |
+| `name` | text | no | — | yes | — |
+| `email` | text | no | — | yes | — |
+| `nopublic` | smallint | no | `0` | — | — |
+| `apionly` | smallint | no | `0` | — | — |
+| `expdate` | bigint | yes | — | — | — |
+| `password` | text | no | `''` | — | — |
+| `resetlogintoken` | bytea | yes | — | — | — |
+| `persistentlogintoken` | bytea | yes | — | yes | — |
+| `signature` | bytea | yes | — | — | — |
+| `description` | text | no | `''` | — | — |
+| `otpsecret` | bytea | yes | — | — | — |
+| `settings` | json | yes | — | — | — |
+
+# Foreign Keys
+
+- `contact` → [contacts](/entities/contacts.md) (`contacts.ID`)
+
+# Enums
+
+### `activity`
+
+`0` = ACTIVE · `1` = DEACTIVATED · `2` = DELETED
+
+# Indexes
+
+- `fk_users_contact` — btree, partial on `contact`
+- `s_users_email` — gin on `email`
+- `s_users_name` — gin on `name`
+- `u_users_email` — btree, unique on `lower(email)`
+- `u_users_name` — btree, unique on `lower(name)`
+- `u_users_persistentlogintoken` — btree, unique, partial on `persistentlogintoken`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listUsers`
+- get: `getUser`
+- exists: `existsUser`
+<!-- okf:generated:end -->
+
+# Notes
+
+Resolve assignees/ownership here; user names may not match contact names.

package/okf/entities/weblets.md

@@ -0,0 +1,66 @@
+---
+type: ZeyOS Entity
+title: Weblets
+description: UI modules with view/type metadata.
+resource: zeyos://api/weblets
+tags: [platform, generated]
+api_backed: true
+list_operation: listWeblets
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `creator` | integer | yes | — | — | — |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `application` | integer | yes | — | yes | [applications](/entities/applications.md) |
+| `activity` | smallint | no | `0` | — | — |
+| `name` | text | no | — | yes | — |
+| `identifier` | character varying(200) | no | — | yes | — |
+| `view` | text | no | `''` | — | — |
+| `type` | smallint | no | `0` | — | — |
+| `width` | smallint | no | `0` | — | — |
+| `height` | smallint | no | `0` | — | — |
+| `svgpath` | text | no | `''` | — | — |
+| `color` | character varying(6) | no | `''` | — | — |
+| `mimetype` | text | no | `'text/x-zymba'` | — | — |
+| `langaliases` | json | yes | — | — | — |
+| `binfile` | integer | yes | — | yes | [binfiles](/entities/binfiles.md) |
+| `url` | text | no | `''` | — | — |
+
+# Foreign Keys
+
+- `application` → [applications](/entities/applications.md) (`applications.ID`)
+- `binfile` → [binfiles](/entities/binfiles.md) (`binfiles.ID`)
+
+# Enums
+
+### `activity`
+
+`0` = ACTIVE · `1` = DEACTIVATED · `2` = DELETED
+
+### `type`
+
+`0` = INTEGRATED · `1` = STANDALONE · `2` = DETACHED · `3` = POPUP_FRAMED · `4` = POPUP_PLAIN · `5` = EMBEDDED_FRAMED · `6` = EMBEDDED_COLLAPSED · `7` = EMBEDDED_PLAIN
+
+# Indexes
+
+- `fk_weblets_application` — gin, partial on `application`
+- `fk_weblets_binfile` — btree, partial on `binfile`
+- `s_weblets_identifier` — gin on `identifier`
+- `s_weblets_name` — gin on `name`
+- `u_weblets_identifier` — btree, unique on `identifier`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listWeblets`
+- get: `getWeblet`
+- exists: `existsWeblet`
+<!-- okf:generated:end -->

package/okf/index.md

@@ -0,0 +1,11 @@
+---
+okf_version: 0.1
+source_snapshot: 19d7df6ae9aa
+---
+
+# ZeyOS Knowledge Bundle
+
+* [Entities](entities/) - 64 API-backed entity concepts (schema, foreign keys, enums, indexes, operations).
+* [Metrics](metrics/) - Business metric definitions.
+* [Playbooks](playbooks/) - Step-by-step query workflows.
+* [Concepts](concepts/) - Cross-cutting query rules and footguns.

package/okf/log.md

@@ -0,0 +1,4 @@
+# OKF Update Log
+
+## 2026-06-22
+* **Initialization**: OKF bundle initialized with 64 entity concepts.

package/okf/metrics/cash-received.md

@@ -0,0 +1,10 @@
+---
+type: Metric
+title: Cash Received
+description: "Cash collected (settlement basis) over a date window."
+tags: [billing, payments]
+---
+
+**Definition.** Sum of `amount` over [payments](/entities/payments.md) with `date` in the window. This is cash basis — distinct from [invoiced-net-revenue](/metrics/invoiced-net-revenue.md) (accrual/billed basis).
+
+Separate direct account payments from transaction-linked payments if the answer needs it. Sum client-side; there is no server-side SUM.

package/okf/metrics/index.md

@@ -0,0 +1,6 @@
+# Metrics
+
+* [Cash Received](cash-received.md) - Cash collected (settlement basis) over a date window.
+* [Invoiced Net Revenue](invoiced-net-revenue.md) - Net invoiced revenue from billing invoices over a date window.
+* [Open Customers](open-customers.md) - Count of active customer accounts.
+* [Overdue Receivables](overdue-receivables.md) - Receivables in collection, via dunning — not from transactions alone.

package/okf/metrics/invoiced-net-revenue.md

@@ -0,0 +1,16 @@
+---
+type: Metric
+title: Invoiced Net Revenue
+description: "Net invoiced revenue from billing invoices over a date window."
+tags: [billing, revenue]
+---
+
+**Definition.** Sum of `netamount` over [transactions](/entities/transactions.md) where `type = 3` (billing invoice) and `date` falls in the window. For *net after credits*, also sum `type = 4` (billing credit) and subtract.
+
+**Why `date`, not `lastmodified`.** `date` is the business-effective invoice date; `lastmodified` is change tracking. See [dates-unix-seconds](/concepts/dates-unix-seconds.md).
+
+**No server-side SUM.** `list` the matching rows (high `--limit`, up to 10000) with `netamount` and add them up client-side. See [counting-and-sums](/concepts/counting-and-sums.md).
+
+**Do not** add `"visibility":0` — `transactions` has no such column and it 400s. See [visibility-column](/concepts/visibility-column.md).
+
+Related playbook: [revenue-this-year](/playbooks/revenue-this-year.md).

package/okf/metrics/open-customers.md

@@ -0,0 +1,14 @@
+---
+type: Metric
+title: Open Customers
+description: "Count of active customer accounts."
+tags: [crm]
+---
+
+**Definition.** Count of [accounts](/entities/accounts.md) where `type = 1` (CUSTOMER), excluding archived (`visibility = 0`).
+
+```bash
+zeyos count accounts --filter '{"type":1,"visibility":0}'
+```
+
+Count server-side (`count`), never `list` + row length. See [counting-and-sums](/concepts/counting-and-sums.md). State the definition you used ("customer = type 1, excluding archived").

package/okf/metrics/overdue-receivables.md

@@ -0,0 +1,12 @@
+---
+type: Metric
+title: Overdue Receivables
+description: "Receivables in collection, via dunning — not from transactions alone."
+tags: [collections]
+---
+
+**Definition.** Overdue/in-collection exposure is tracked through [dunning](/entities/dunning.md) notices and the [dunning2transactions](/entities/dunning2transactions.md) junction, not inferred from [transactions](/entities/transactions.md) alone.
+
+**operationId trap.** Use `listDunningNotices` / `getDunningNotice` and `listDunningToTransactions`. See [operationid-vocabulary](/concepts/operationid-vocabulary.md).
+
+Separate invoice exposure (the receivable) from collection stage and next action.

package/okf/playbooks/customer-360.md

@@ -0,0 +1,12 @@
+---
+type: Playbook
+title: Customer 360
+description: "Assemble a cross-domain summary for one customer."
+tags: [crm]
+---
+
+1. Resolve the account first ([accounts](/entities/accounts.md) by `customernum`/`lastname`).
+2. Open work: [tickets](/entities/tickets.md) for the account.
+3. Billing: [transactions](/entities/transactions.md) (invoices/credits) and [payments](/entities/payments.md).
+4. Mail: resolve [contacts](/entities/contacts.md) email, then [messages](/entities/messages.md) (no direct account FK — see the entity note).
+5. Present facts and inference separately; state interpretations.

package/okf/playbooks/index.md

@@ -0,0 +1,5 @@
+# Playbooks
+
+* [Customer 360](customer-360.md) - Assemble a cross-domain summary for one customer.
+* [Revenue This Year](revenue-this-year.md) - Answer "what have we invoiced/collected this year?" end to end.
+* [Ticket Work Packet](ticket-work-packet.md) - Trace a ticket down to its tasks and follow-ups.

package/okf/playbooks/revenue-this-year.md

@@ -0,0 +1,19 @@
+---
+type: Playbook
+title: Revenue This Year
+description: "Answer \"what have we invoiced/collected this year?\" end to end."
+tags: [billing]
+---
+
+1. Decide invoiced revenue vs cash received. If unspecified, state you are using invoiced net revenue ([invoiced-net-revenue](/metrics/invoiced-net-revenue.md)).
+2. Normalize the window to Unix **seconds** (e.g. 2026-01-01 = 1767225600). See [dates-unix-seconds](/concepts/dates-unix-seconds.md).
+3. `list` billing invoices ([transactions](/entities/transactions.md) `type = 3`) in the window with `netamount`; high `--limit`.
+4. If net-after-credits, `list` `type = 4` and subtract.
+5. Sum client-side and report the figure (do not describe the plan — run it).
+
+```bash
+zeyos list transactions \
+  --filter '{"type":3,"date":{">=":1767225600,"<":1798761600}}' \
+  --fields ID,transactionnum,date,netamount --limit 10000 --json \
+  | python3 -c 'import sys,json; r=json.load(sys.stdin); print(sum(x.get("netamount",0) for x in r.get("data",r)))'
+```

package/okf/playbooks/ticket-work-packet.md

@@ -0,0 +1,11 @@
+---
+type: Playbook
+title: Ticket Work Packet
+description: "Trace a ticket down to its tasks and follow-ups."
+tags: [work]
+---
+
+1. Resolve the [ticket](/entities/tickets.md) (`ticketnum`/`name`).
+2. [tasks](/entities/tasks.md) where `ticket` = that ID (use the `filters` form for the FK — see [filters-vs-filter](/concepts/filters-vs-filter.md)).
+3. [actionsteps](/entities/actionsteps.md) bound to the ticket/its tasks for smaller follow-ups.
+4. Summarize open vs closed (closed ticket = `status` IN [9, 11]).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",
@@ -29,8 +29,12 @@
   "files": [
     "src",
     "scripts/generate-client.mjs",
+    "scripts/generate-okf.mjs",
+    "scripts/lib",
+    "scripts/data",
     "openapi",
     "docs",
+    "okf",
     "samples/crm",
     "samples/dashboard",
     "samples/kanban",
@@ -43,7 +47,10 @@
     "node": ">=18"
   },
   "scripts": {
-    "generate": "node scripts/generate-client.mjs",
+    "generate": "node scripts/generate-client.mjs && node scripts/generate-okf.mjs",
+    "okf:build": "node scripts/generate-okf.mjs",
+    "okf:check": "node --test test/okf.test.js",
+    "okf:refine": "node test/agent-protocol/harness/refine-okf.mjs",
     "test": "node scripts/test.mjs",
     "test:cli-integration": "node --test cli/test/integration.mjs",
     "test:agent-protocol": "node test/agent-protocol/harness/run.mjs",