@zeyos/client 0.3.0 → 0.5.0

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/metrics/stock-movement-by-storage.md

@@ -0,0 +1,10 @@
+---
+type: Metric
+title: Stock Movement by Storage
+description: "Booked/reserved/cancelled stock movement quantities grouped per storage."
+tags: [commerce]
+---
+
+**Definition.** Group [stocktransactions](/entities/stocktransactions.md) for an item by `storage`, summing `amount` per `flag` (0 BOOKED, 1 RESERVED, 2 CANCELLED).
+
+Never report one storage — or one flag — as the global stock level. `stocktransactions` has no `visibility` column. See [counting-and-sums](/concepts/counting-and-sums.md).

package/okf/metrics/supplier-delivery-performance.md

@@ -0,0 +1,10 @@
+---
+type: Metric
+title: Supplier Delivery Performance
+description: "Ordered vs invoiced value, delivery timeliness and price variance per supplier."
+tags: [commerce]
+---
+
+**Definition.** Per supplier `account`, over a declared window and one currency, from [transactions](/entities/transactions.md): `ordered_value` = Σ `netamount` (type 6), `invoiced_value` = Σ `netamount` (type 8), `price_variance` = invoiced − ordered, on-time from type-7 delivery dates vs the order `duedate`.
+
+Keep ordered, delivered and invoiced quantities distinct. Exclude cancelled records by documented policy. See [supplier-scorecard](/playbooks/supplier-scorecard.md).

package/okf/playbooks/activity-timeline.md

@@ -0,0 +1,11 @@
+---
+type: Playbook
+title: Activity Timeline
+description: "Chronological, source-labelled timeline for a record."
+tags: [collaboration]
+---
+
+1. Resolve the anchor record (e.g. a [ticket](/entities/tickets.md)).
+2. Gather the directly-linked items by their own date fields: [tasks](/entities/tasks.md), [actionsteps](/entities/actionsteps.md), [messages](/entities/messages.md) (and [records](/entities/records.md)/[comments](/entities/comments.md)/[files](/entities/files.md) where present).
+3. Merge into one stream sorted ascending by timestamp; keep each entry's `type` (provenance).
+4. Emit one object per line (NDJSON) with `timestamp,type,id,parentId,summary`. Keep root and comment attachments distinguishable.

package/okf/playbooks/calendar-availability.md

@@ -0,0 +1,11 @@
+---
+type: Playbook
+title: Calendar Availability
+description: "Find free slots and conflicts from appointments."
+tags: [work]
+---
+
+1. Resolve the user (`$ME`) and timezone; normalize the window to a half-open `[start,end)` in Unix **seconds**.
+2. List [appointments](/entities/appointments.md) for the user overlapping the window (`datefrom`/`dateto`).
+3. Sort busy intervals; a gap `>=` the requested duration is a free slot (two intervals conflict when `aFrom < bTo && bFrom < aTo`).
+4. Report Unix seconds + ISO and the timezone used. Create only after exact confirmation; an [invitation](/entities/invitations.md) is not proof an email was sent. See [calendar-timezones](/concepts/calendar-timezones.md).

package/okf/playbooks/campaign-recipient-coverage.md

@@ -0,0 +1,12 @@
+---
+type: Playbook
+title: Campaign Recipient Coverage
+description: "Which participants have no recorded sent-mailing recipient entry."
+tags: [outreach]
+---
+
+1. Resolve the [campaign](/entities/campaigns.md) and its [participants](/entities/participants.md).
+2. Identify the sent mailing(s): [messages](/entities/messages.md) in the mailings/sent box.
+3. List [mailingrecipients](/entities/mailingrecipients.md) for the sent mailing.
+4. Anti-join participants against those recipients. A draft mailing does **not** count.
+5. Label the reason "no recorded mailing recipient" — not "never contacted". Membership, recipient record, send and read are separate facts.

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/document-approval.md

@@ -0,0 +1,10 @@
+---
+type: Playbook
+title: Document Approval
+description: "Select the official document and gate finalization."
+tags: [knowledge]
+---
+
+1. Search formal [documents](/entities/documents.md); read `status` (0 DRAFT … 4 FINAL, 5 OBSOLETE), `name`, `filename`.
+2. Authority is status + type, not freshness: a FINAL document outranks a newer OBSOLETE one and a draft [note](/entities/notes.md). See [official-versus-latest](/concepts/official-versus-latest.md).
+3. To finalize: fetch the exact ID + current status, preview, require exact confirmation, `updateDocument` one ID, then re-read and report old/new status. Never bulk-finalize by fuzzy name.

package/okf/playbooks/duplicate-account-review.md

@@ -0,0 +1,11 @@
+---
+type: Playbook
+title: Duplicate Account Review
+description: "Find and explain duplicate-account candidates safely."
+tags: [crm]
+---
+
+1. Define the population and active scope; normalize comparison fields without losing originals (see [null-empty-missing](/concepts/null-empty-missing.md)).
+2. Score candidate pairs from deterministic evidence: exact `customernum`, exact normalized email (via [contacts](/entities/contacts.md)), exact normalized name/address (strong); near-name-only (weak/low confidence).
+3. Sort by score; explain reasons + confidence. Detection is read-only and separate from remediation.
+4. A "clean up" request becomes a bounded preview (exact IDs + proposed per-ID action) requiring a human decision — never a bulk merge/archive/delete.

package/okf/playbooks/effective-customer-price.md

@@ -0,0 +1,11 @@
+---
+type: Playbook
+title: Effective Customer Price
+description: "Resolve a customer price: price-list override, else item default."
+tags: [commerce]
+---
+
+1. Resolve the customer's assigned price list via [pricelists2accounts](/entities/pricelists2accounts.md) (`listPriceListsToAccounts`).
+2. For each item, look up a [prices](/entities/prices.md) row in that price list (`source = pricelist-override`).
+3. If none, fall back to the item's own `sellingprice` (`source = item-default`).
+4. Report `{itemId, price, currency, source, minAmount}`; always name the source. See [filters-vs-filter](/concepts/filters-vs-filter.md).

package/okf/playbooks/index.md

@@ -0,0 +1,13 @@
+# Playbooks
+
+* [Activity Timeline](activity-timeline.md) - Chronological, source-labelled timeline for a record.
+* [Calendar Availability](calendar-availability.md) - Find free slots and conflicts from appointments.
+* [Campaign Recipient Coverage](campaign-recipient-coverage.md) - Which participants have no recorded sent-mailing recipient entry.
+* [Customer 360](customer-360.md) - Assemble a cross-domain summary for one customer.
+* [Document Approval](document-approval.md) - Select the official document and gate finalization.
+* [Duplicate Account Review](duplicate-account-review.md) - Find and explain duplicate-account candidates safely.
+* [Effective Customer Price](effective-customer-price.md) - Resolve a customer price: price-list override, else item default.
+* [Missing Billing Addresses](missing-billing-addresses.md) - Anti-join: active customers with no billing address.
+* [Revenue This Year](revenue-this-year.md) - Answer "what have we invoiced/collected this year?" end to end.
+* [Supplier Scorecard](supplier-scorecard.md) - Rank suppliers and score procurement performance.
+* [Ticket Work Packet](ticket-work-packet.md) - Trace a ticket down to its tasks and follow-ups.

package/okf/playbooks/missing-billing-addresses.md

@@ -0,0 +1,12 @@
+---
+type: Playbook
+title: Missing Billing Addresses
+description: "Anti-join: active customers with no billing address."
+tags: [crm]
+---
+
+1. List active customers ([accounts](/entities/accounts.md) `type = 1`, `visibility = 0`).
+2. List billing [addresses](/entities/addresses.md) (`type = 1`). `addresses` has **no** `visibility` column — do not filter it.
+3. Keep customers whose ID has no matching `addresses.account` (the anti-join).
+4. Optionally flag whether each still has a shipping address (`type = 0`).
+5. Export with a stable header and declared null representation. See [account-address-completeness](/metrics/account-address-completeness.md).

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/supplier-scorecard.md

@@ -0,0 +1,10 @@
+---
+type: Playbook
+title: Supplier Scorecard
+description: "Rank suppliers and score procurement performance."
+tags: [commerce]
+---
+
+1. Resolve the item and supplier [accounts](/entities/accounts.md) (`type = 2`).
+2. For sourcing: read [suppliers](/entities/suppliers.md) links (`price`, `minamount`, `deliverytime`, `stock`); a supplier is eligible only if `minamount <= quantity`. State the ranking policy before ranking.
+3. For performance: group procurement [transactions](/entities/transactions.md) (types 6/7/8) by supplier over a declared window + currency. See [supplier-delivery-performance](/metrics/supplier-delivery-performance.md). Never place or transmit a procurement transaction.

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.5.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,10 +47,14 @@
     "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",
-    "test:agent-loop": "node test/agent-protocol/harness/loop.mjs"
+    "test:agent-loop": "node test/agent-protocol/harness/loop.mjs",
+    "test:agent-validate": "node test/agent-protocol/harness/validate-live.mjs"
   }
 }