@zeyos/client 0.1.0

package/docs/04-agent-workflows/01-agent-quickstart.md

@@ -0,0 +1,147 @@
+---
+sidebar_position: 2
+sidebar_label: Agent Quickstart
+---
+
+# Agent Quickstart
+
+This guide gets a coding agent from zero to authenticated CRUD access with the ZeyOS CLI.
+
+## Install or Run the CLI
+
+From this repository:
+
+```bash
+npm install
+node cli/bin/zeyos.mjs --help
+```
+
+For a global `zeyos` command during development:
+
+```bash
+npm link cli/
+zeyos --help
+```
+
+## Load the ZeyOS Skills
+
+Before doing real work, install the bundled skill packs so the agent picks up ZeyOS's query conventions (entity model, `filters` usage, safe writes):
+
+```bash
+zeyos skills list                 # see what's available
+zeyos skills install              # install all into .claude/skills (or .codex)
+```
+
+This is the recommended entry point for an agent: the skills encode how to resolve names to IDs, which resource to query first, and how to escalate from the CLI to `@zeyos/client`.
+
+## Authenticate
+
+Interactive login:
+
+```bash
+zeyos login
+```
+
+Pre-fill login parameters:
+
+```bash
+zeyos login \
+  --base-url https://cloud.zeyos.com/demo \
+  --client-id myapp \
+  --secret "$ZEYOS_CLIENT_SECRET"
+```
+
+This still starts the OAuth authorization-code flow and requires a browser redirect or pasted code. For fully unattended agents, inject `ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, and optionally `ZEYOS_REFRESH_TOKEN`, `ZEYOS_CLIENT_ID`, and `ZEYOS_CLIENT_SECRET` through the environment.
+
+The CLI stores credentials in `.zeyos/auth.json` in the current project tree, or in `~/.config/zeyos/credentials.json` when `--global` is used.
+
+## Verify the Session
+
+Check the current user:
+
+```bash
+zeyos whoami --json
+```
+
+`whoami` hides access tokens by default. Use `zeyos whoami --show-token --json` only when the token must be handed to another local tool.
+
+Discover which curated resources the CLI can operate on directly:
+
+```bash
+zeyos resources
+```
+
+Inspect a resource's fields, types and enum values before querying (works offline, no login needed):
+
+```bash
+zeyos describe tickets
+```
+
+## Read Data
+
+List tickets in machine-readable form:
+
+```bash
+zeyos list tickets --json
+```
+
+List only the fields an agent needs:
+
+```bash
+zeyos list tickets \
+  --fields ID,ticketnum,name,status,priority,lastmodified \
+  --filter '{"visibility":0}' \
+  --sort -lastmodified \
+  --limit 20 \
+  --json
+```
+
+Fetch one record:
+
+```bash
+zeyos get ticket 42 --all --json
+```
+
+Count matching records:
+
+```bash
+zeyos count tickets --filter '{"visibility":0,"status":4}' --json
+```
+
+## Write Data
+
+Create with JSON-first input:
+
+```bash
+zeyos create ticket \
+  --data '{"name":"Follow up with customer","status":0,"priority":2,"visibility":0}' \
+  --json
+```
+
+Update with JSON-first input:
+
+```bash
+zeyos update ticket 42 \
+  --data '{"status":4,"priority":3}' \
+  --json
+```
+
+Delete interactively:
+
+```bash
+zeyos delete ticket 42
+```
+
+Delete non-interactively only when the automation has already decided the record must be removed:
+
+```bash
+zeyos delete ticket 42 --force
+```
+
+## Safe Defaults for Agents
+
+- Use `--json` unless a human is actively reading the output.
+- Include `visibility: 0` in filters for normal business views.
+- Prefer `--data '<json>'` over many separate flags in automation.
+- Run `zeyos resources` before assuming a resource is CLI-supported.
+- Escalate to [`@zeyos/client`](./03-cli-coverage-and-escalation.md) when the CLI resource registry is not enough.

package/docs/04-agent-workflows/02-agent-recipes.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 3
+sidebar_label: Agent Recipes
+---
+
+# Agent Recipes
+
+These workflows are designed for coding agents and shell automation. Every example is safe to convert into CI jobs, local scripts, or ad hoc operational tooling.
+
+## Work a Ticket Queue
+
+List active tickets with only the fields you need:
+
+```bash
+zeyos list tickets \
+  --fields ID,ticketnum,name,status,priority,assigneduser,lastmodified \
+  --filter '{"visibility":0,"status":4}' \
+  --sort -lastmodified \
+  --limit 50 \
+  --json
+```
+
+Count the backlog before acting:
+
+```bash
+zeyos count tickets --filter '{"visibility":0,"status":0}' --json
+```
+
+Move a ticket to a new status:
+
+```bash
+zeyos update ticket 42 --data '{"status":7}' --json
+```
+
+## Create a Follow-up Ticket
+
+```bash
+zeyos create ticket \
+  --data '{"name":"Escalate billing issue","status":0,"priority":3,"account":15,"visibility":0}' \
+  --json
+```
+
+Use `zeyos get ticket <id> --json` immediately after creation if the workflow needs server-confirmed fields or related data.
+
+## Query Accounts for an Agent-Facing CRM View
+
+Use field aliases and joins when you need a compact response:
+
+```bash
+zeyos list accounts \
+  --fields '{"Id":"ID","Name":"lastname","City":"contact.city","Agent":"assigneduser.name"}' \
+  --filter '{"visibility":0}' \
+  --sort +lastname \
+  --limit 25 \
+  --json
+```
+
+## Pull Tasks for a Project or Ticket
+
+```bash
+zeyos list tasks \
+  --fields ID,tasknum,name,status,priority,duedate \
+  --filter '{"visibility":0,"project":123}' \
+  --sort +duedate \
+  --json
+```
+
+```bash
+zeyos list tasks \
+  --fields ID,tasknum,name,status,priority,duedate \
+  --filter '{"visibility":0,"ticket":42}' \
+  --json
+```
+
+## Paginate Deterministically
+
+```bash
+zeyos list tickets \
+  --filter '{"visibility":0}' \
+  --sort -lastmodified \
+  --limit 100 \
+  --offset 0 \
+  --json
+```
+
+Advance by incrementing `--offset` yourself. For long-running jobs, always keep the sort explicit so the ordering stays stable.
+
+## Pipe to `jq`
+
+Extract IDs:
+
+```bash
+zeyos list tickets --fields ID,name --filter '{"visibility":0}' --json | jq '.[].ID'
+```
+
+Extract the current access token for another tool:
+
+```bash
+zeyos whoami --show-token --json | jq -r '.accessToken'
+```
+
+Treat printed access tokens as secrets. Avoid writing them to logs, shared shell history, or agent transcripts.
+
+## Destructive Guardrails
+
+- `zeyos delete` prompts by default. Keep that behavior in human-in-the-loop sessions.
+- Use `--force` only in automation that already has a clear selection rule.
+- Prefer `count` or a dry-run `list` before a bulk action.
+- If a workflow needs unsupported resources, raw request control, or custom retry logic, move it to [`@zeyos/client`](./03-cli-coverage-and-escalation.md).

package/docs/04-agent-workflows/03-cli-coverage-and-escalation.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 4
+sidebar_label: CLI Coverage and Escalation
+---
+
+# CLI Coverage and Escalation
+
+The CLI is the default interface for coding agents, but it intentionally covers a curated registry instead of the full API surface.
+
+## What the CLI Covers Directly
+
+The command `zeyos resources` is the source of truth for CLI-supported resource types. At the time of writing, the curated registry includes:
+
+| Resource | Operations |
+|----------|------------|
+| `account`, `appointment`, `campaign`, `contact`, `document`, `event`, `file`, `invitation`, `item`, `message`, `note`, `opportunity`, `payment`, `project`, `storage`, `task`, `ticket`, `transaction` | `list`, `get`, `create`, `update`, `delete` |
+| `group`, `user` | `list`, `get` |
+
+Plural names and common aliases such as `tickets`, `docs`, `invoice`, and `crm` are resolved by the CLI, but the underlying coverage boundary is still the registry above.
+
+## What the CLI Does Not Try to Cover
+
+Switch away from the CLI when you need:
+
+- Resources that are present in the generated API client but missing from `zeyos resources`
+- Low-level request control beyond the registry-backed commands
+- Browser session behavior or embedded app flows
+- Full access to generated operations such as `listApplications`, `listServices`, `listResources`, `listPermissions`, or `listWeblets`
+- Custom auth overrides, raw responses, or path-and-method requests
+
+## Escalation Path
+
+### 1. Stay on the CLI if the resource exists in the registry
+
+This remains the best option for shell automation, quick operational tooling, and JSON-first CRUD workflows.
+
+### 2. Move to `@zeyos/client` for the full generated API surface
+
+```js
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo/',
+  auth: {
+    mode: 'oauth',
+    oauth: {
+      tokenStore: new MemoryTokenStore({ accessToken: process.env.ZEYOS_TOKEN }),
+    },
+  },
+});
+
+const services = await client.api.listServices({ limit: 20 });
+```
+
+Use the JavaScript client whenever the CLI registry is insufficient or the workflow needs request-level control.
+
+### 3. Drop to raw REST/OpenAPI when your runtime is not JavaScript
+
+Use the API reference and OpenAPI files when you are implementing integrations in another language or building a custom SDK.
+
+## Rule of Thumb
+
+- If `zeyos resources` shows the resource and the built-in command shape is enough, stay with the CLI.
+- If the resource exists in the API but not in the CLI registry, move to `@zeyos/client`.
+- If you are not using JavaScript at all, use the REST/OpenAPI reference directly.

package/docs/04-agent-workflows/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Agent Workflows",
+  "position": 5,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "description": "CLI-first workflows for coding agents, automation scripts, and operational tooling built on top of ZeyOS."
+  }
+}

package/docs/04-sample-apps/01-kanban.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 1
+sidebar_label: Kanban Board
+---
+
+# Kanban Board
+
+The `samples/kanban/` application shows how to build a browser-based work queue on top of ZeyOS using plain ES modules and the generated JavaScript client.
+
+## Problem Solved
+
+Use this sample when you need a UI for operators who move work through statuses, inspect details, and create follow-up work without leaving a lightweight browser app.
+
+## Auth Model
+
+The sample supports both browser auth models used throughout this docs set:
+
+- **Token mode** using a pre-obtained access token and optional stored refresh token
+- **Session mode** by probing `/oauth2/v1/userinfo` with `credentials: 'include'`
+
+Configuration can come from:
+
+- `data-zeyos-*` attributes in `samples/kanban/index.html`
+- persisted `localStorage` values
+- the `window.ZeyOS` console API
+
+For long-lived browser sessions, prefer session mode or move OAuth refresh to a backend. Session mode only works from the same origin or when the ZeyOS instance allows credentialed CORS, so token mode is usually the local-development path. The sample does not embed client credentials for browser-side refresh.
+
+## Main API Calls
+
+| Operation | Usage in the sample |
+|-----------|---------------------|
+| `listTickets` | Load the board columns and context-filtered ticket lists |
+| `getTicket` | Fetch the full ticket for the detail dialog |
+| `createTicket` | Create new tickets from the modal |
+| `updateTicket` | Move tickets between columns and edit ticket details |
+| `deleteTicket` | Remove tickets from the board |
+| `listTasks` | Load tasks linked to a ticket |
+| `listProjects` | Populate the project context dropdown |
+
+## Reusable Patterns
+
+- **Auth boot sequence**: URL resolution, token detection, session probe, then app boot
+- **Optimistic UI update**: move the card first, then confirm with `updateTicket`, then revert on failure
+- **Explicit update body**: all ticket updates in this sample use `{ ID, body }` for clarity (the flat spread form `{ ID, status }` also works)
+- **Context filtering**: a single filter object drives board views such as “all tickets” or “project tickets”
+- **Persistent UI settings**: board columns and runtime config live in `localStorage`
+
+## Safe to Copy
+
+The following pieces are good starting points for a new UI:
+
+- the token/session boot sequence in `samples/kanban/js/main.js`
+- the session detection helper in `samples/kanban/js/auth.js`
+- the optimistic update pattern around `updateTicket`
+- the `window.ZeyOS` console API for local development and troubleshooting
+
+When copying code outside this repository, replace source-tree imports such as `../../../src/index.js` with an import path that exists in your app: an npm package import, a vendored copy of `src/`, or a local symlink.
+
+## Run Locally
+
+Serve the repository root with any static file server:
+
+```bash
+cd /path/to/zeyos/client
+python3 -m http.server 8080
+```
+
+Then open:
+
+```text
+http://localhost:8080/samples/kanban/
+```
+
+## Console API
+
+| Method | Description |
+|--------|-------------|
+| `ZeyOS.setUrl(url)` | Set the ZeyOS instance URL |
+| `ZeyOS.setToken(access, refresh?)` | Persist access and optional refresh tokens |
+| `ZeyOS.status()` | Print effective connection state |
+| `ZeyOS.logout()` | Clear stored config and reload |
+| `ZeyOS.reconnect()` | Reload and re-run the auth boot sequence |
+
+## What to Read Next
+
+- [Browser UI Playbook](../05-tutorials/02-build-your-own-zeyos-frontend.md)
+- [Practical Guide](../02-javascript-client/04-practical-guide.md)
+- [Kanban sample README](../../samples/kanban/README.md)

package/docs/04-sample-apps/02-crm.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 2
+sidebar_label: CRM Account List
+---
+
+# CRM Account List
+
+The `samples/crm/` application shows how to build a read-heavy account UI with server-side search, joined contact fields, modal editing, and predictable pagination.
+
+## Problem Solved
+
+Use this sample when you need a compact CRUD interface for operational data such as accounts or contacts and you want the server, not the browser, to do the filtering and sorting work.
+
+## Auth Model
+
+The sample uses the same dual browser model as the Kanban app:
+
+- **Token mode** with a pre-obtained access token and optional stored refresh token
+- **Session mode** with a `/oauth2/v1/userinfo` probe
+
+Configuration can come from `data-zeyos-*` attributes, `localStorage`, or the `window.ZeyOS` console API.
+
+For long-lived browser sessions, prefer session mode or move OAuth refresh to a backend. Session mode only works from the same origin or when the ZeyOS instance allows credentialed CORS, so token mode is usually the local-development path. The sample keeps browser code free of client credentials.
+
+## Main API Calls
+
+| Operation | Usage in the sample |
+|-----------|---------------------|
+| `listAccounts` | Fetch paginated CRM rows with aliased and joined fields |
+| `getAccount` | Load the full record before editing |
+| `createAccount` | Create new accounts from the modal |
+| `updateAccount` | Apply modal edits via `{ ID, body: data }` |
+| `deleteAccount` | Remove records from the dataset |
+
+## Reusable Patterns
+
+- **Object-form `fields`**: the UI requests aliased fields such as `City: 'contact.city'`
+- **Server-side search**: full-text queries use the `query` parameter instead of client-side filtering
+- **Server-side sorting**: column headers map friendly names back to raw API fields
+- **Update helpers**: update helpers use `{ ID, body: data }` to keep path parameters separate from changed fields
+- **Token persistence**: runtime tokens are stored in `localStorage` for the next page load
+
+## Safe to Copy
+
+The sample is a strong reference for:
+
+- dot-notation joins with aliased output fields
+- building sort maps from UI column names to API field paths
+- debounced search that resets pagination
+- small browser apps that still keep auth, state, API, and UI concerns separate
+
+When copying code outside this repository, replace source-tree imports such as `../../../src/index.js` with an import path that exists in your app: an npm package import, a vendored copy of `src/`, or a local symlink.
+
+## Run Locally
+
+```bash
+cd /path/to/zeyos/client
+python3 -m http.server 8080
+```
+
+Open:
+
+```text
+http://localhost:8080/samples/crm/
+```
+
+## Console API
+
+| Method | Description |
+|--------|-------------|
+| `ZeyOS.setUrl(url)` | Set the ZeyOS instance URL |
+| `ZeyOS.setToken(access, refresh?)` | Persist access and optional refresh tokens |
+| `ZeyOS.status()` | Print connection state, search, sort, and page info |
+| `ZeyOS.logout()` | Clear stored config and reload |
+| `ZeyOS.reconnect()` | Reload and re-run the auth boot sequence |
+
+## What to Read Next
+
+- [Browser UI Playbook](../05-tutorials/02-build-your-own-zeyos-frontend.md)
+- [Making Requests](../02-javascript-client/03-making-requests.md)
+- [CRM sample README](../../samples/crm/README.md)

package/docs/04-sample-apps/03-dashboard.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 3
+sidebar_label: Dashboard
+---
+
+# Dashboard
+
+The `samples/dashboard/` application shows how to build a read-only operational dashboard that combines multiple ZeyOS queries into one browser view.
+
+## Problem Solved
+
+Use this sample when you need KPI cards, summary charts, and recent-activity panels without building a heavy frontend stack.
+
+## Auth Model
+
+The dashboard follows the same browser auth model as the other samples:
+
+- **Token mode** with a pre-obtained access token and optional stored refresh token
+- **Session mode** via `/oauth2/v1/userinfo`
+
+Configuration can come from `data-zeyos-*` attributes, `localStorage`, or the `window.ZeyOS` console API.
+
+For long-lived browser sessions, prefer session mode or move OAuth refresh to a backend. Session mode only works from the same origin or when the ZeyOS instance allows credentialed CORS, so token mode is usually the local-development path. The sample avoids shipping client credentials in browser code.
+
+## Main API Calls
+
+| Operation | Usage in the sample |
+|-----------|---------------------|
+| `listTickets` with `count: true` | Build total, active, and overdue KPI cards |
+| `listTickets` with explicit fields | Render recent ticket activity |
+| `listAccounts` with `count: true` | Build total account KPIs |
+| `listAccounts` with joins | Render recent account activity |
+
+## Reusable Patterns
+
+- **Parallel data loading**: the dashboard fires independent queries with `Promise.all`
+- **Count-first dashboards**: KPI cards use count-enabled requests instead of loading full datasets
+- **Defensive count handling**: the sample treats count-enabled responses conservatively instead of assuming a single wrapper shape
+- **Read-only browser views**: the app demonstrates a useful UI that never mutates records
+- **Minimal field selection**: each summary query requests only the fields needed for display
+
+## Safe to Copy
+
+The dashboard is a good template for:
+
+- status or backlog overview pages
+- home pages for internal operator portals
+- management dashboards that aggregate a few targeted ZeyOS queries
+- small browser apps that need strong perceived performance from parallel loading
+
+When copying code outside this repository, replace source-tree imports such as `../../../src/index.js` with an import path that exists in your app: an npm package import, a vendored copy of `src/`, or a local symlink.
+
+## Run Locally
+
+```bash
+cd /path/to/zeyos/client
+python3 -m http.server 8080
+```
+
+Open:
+
+```text
+http://localhost:8080/samples/dashboard/
+```
+
+## Console API
+
+| Method | Description |
+|--------|-------------|
+| `ZeyOS.setUrl(url)` | Set the ZeyOS instance URL |
+| `ZeyOS.setToken(access, refresh?)` | Persist access and optional refresh tokens |
+| `ZeyOS.status()` | Print effective connection state |
+| `ZeyOS.logout()` | Clear stored config and reload |
+| `ZeyOS.reconnect()` | Reload and re-run the auth boot sequence |
+
+## What to Read Next
+
+- [Server-Side Integrations](../05-tutorials/03-server-side-integrations.md)
+- [Making Requests](../02-javascript-client/03-making-requests.md)
+- [Dashboard sample README](../../samples/dashboard/README.md)

package/docs/04-sample-apps/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Sample Applications",
+  "position": 7,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "description": "Three ready-to-run sample applications demonstrating different ZeyOS API integration patterns."
+  }
+}

package/docs/05-tutorials/00-application-developers.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 1
+sidebar_label: Application Developers
+---
+
+# Application Developers
+
+This path is for developers building external applications that use ZeyOS as the central source of business data and business logic.
+
+For v1, the scope is explicitly **external integrations**:
+
+- browser UIs
+- server-side services
+- automation backends
+- connected internal tools
+
+These docs do **not** cover authoring native ZeyOS platform artifacts.
+
+## Choose Your Starting Point
+
+| Goal | Start here | Why |
+|------|------------|-----|
+| Decide between browser, token, and server architectures | [Integration Architecture](./01-integration-architecture.md) | Compares auth and deployment models before you write code |
+| Build a browser UI or internal tool | [Browser UI Playbook](./02-build-your-own-zeyos-frontend.md) | Covers session mode, controlled browser token mode, list queries, CRUD, and UI-safe patterns |
+| Build a backend, worker, or scheduled integration | [Server-Side Integrations](./03-server-side-integrations.md) | Covers token storage, refresh, low-level requests, and sync jobs |
+| Reuse working implementation patterns | [Sample Applications](../04-sample-apps/01-kanban.md) | Shows reusable frontend patterns without framework lock-in |
+| Need the full generated surface | [JavaScript Client](../02-javascript-client/01-getting-started.md) | Full API coverage and low-level request escape hatch |
+
+## Recommended Defaults
+
+- Prefer `@zeyos/client` for JavaScript applications.
+- Use `filters` in client code unless you have a reason to stay with raw API `filter`.
+- Include `visibility: 0` for normal business views.
+- Use explicit `body` objects for update operations that also include path parameters such as `ID`.
+- Treat `extdata` and `expand` as separate concepts:
+  - `extdata` exposes custom fields
+  - `expand` inlines JSON or binary columns
+
+## Next Steps
+
+- Read [Integration Architecture](./01-integration-architecture.md)
+- Pick either the [Browser UI Playbook](./02-build-your-own-zeyos-frontend.md) or [Server-Side Integrations](./03-server-side-integrations.md)
+- Use the [API Reference](../01-api-reference/01-data-retrieval.md) and [JavaScript Client docs](../02-javascript-client/03-making-requests.md) as the detailed reference layers