@zeyos/client 0.1.0

package/docs/02-javascript-client/04-practical-guide.md

@@ -0,0 +1,348 @@
+---
+sidebar_label: Practical Guide
+---
+
+# Practical Implementation Guide
+
+This guide documents patterns and gotchas discovered while building a real application on top of the ZeyOS JavaScript client. It supplements the reference documentation with things that only become apparent once you start making actual API calls.
+
+## HTTP Method Conventions
+
+ZeyOS uses an unconventional but consistent REST convention that often surprises developers:
+
+| Operation | HTTP Method | Notes |
+|-----------|-------------|-------|
+| List records | **POST** | Query params (filters, sort, fields) go in the request body |
+| Get a record | **GET** | |
+| Create a record | **PUT** | Not POST — ZeyOS uses PUT for creation |
+| Update a record | **PATCH** | Partial updates; only send fields you want to change |
+| Delete a record | **DELETE** | |
+| Check existence | **HEAD** | Returns `true` (no body) on success |
+
+The most important one to internalise: **list operations are POST requests**. This makes sense once you consider that complex queries with nested filters would quickly exceed URL length limits as query strings.
+
+## Passing the Request Body for Update Operations
+
+Generated methods accept the natural flat style for operations that have both a path parameter and a request body:
+
+```js
+await client.api.updateTicket({ ID: 42, status: 4, priority: 2 });
+```
+
+The client routes known path/query/header parameters to the request URL and sends the remaining non-reserved keys as the body. Explicit `body` and `data` keys are still supported when you want to separate those concerns yourself:
+
+```js
+await client.api.updateTicket({ ID: 42, body: { status: 4, priority: 2 } });
+await client.api.updateTask({ ID: taskId, data: { name: 'New name', duedate: ts } });
+```
+
+For low-level `client.request()` calls, prefer explicit `body` because there is no generated operation metadata to tell the client which keys are URL parameters.
+
+## `filter` vs `filters`
+
+The ZeyOS API exposes two distinct filtering parameters, and the one you need depends on the field type:
+
+| Parameter | Use for | Example |
+|-----------|---------|---------|
+| `filter` | Simple scalar fields (integers, strings, enums) | `filter: { visibility: 0, status: 1 }` |
+| `filters` | GIN-indexed fields — foreign key references and array-type columns | `filters: { ticket: ticketId, project: projectId }` |
+
+In practice this means:
+
+```js
+// Listing tickets — status and visibility are scalar fields → use 'filter'
+const tickets = await client.api.listTickets({
+  filters: { visibility: 0, project: projectId },
+  sort: ['-lastmodified'],
+  limit: 500,
+});
+
+// Listing tasks for a ticket — 'ticket' is a GIN-indexed FK → use 'filters'
+const tasks = await client.api.listTasks({
+  fields: ['ID', 'tasknum', 'name', 'duedate', 'assigneduser'],
+  filters: { ticket: ticketId, visibility: 0 },
+  sort: ['+name'],
+  limit: 200,
+});
+```
+
+:::tip
+When in doubt, use `filters`. It appears to handle both scalar and FK fields correctly. Using `filter` for a FK field silently returns unfiltered results rather than throwing an error, which makes this particularly easy to miss.
+:::
+
+## Always Include `visibility: 0`
+
+ZeyOS records have a `visibility` field that controls soft-deletion and archiving. Records with `visibility > 0` are typically hidden from normal views. Always include `visibility: 0` in your filters unless you intentionally want to retrieve archived or deleted records:
+
+```js
+const filter = { visibility: 0 };
+// Add resource-specific filters after
+if (projectId) filter.project = projectId;
+```
+
+## Normalising List Responses
+
+List operations are not perfectly uniform across the whole surface area. Use the shared helper so every call site follows the same response-shape handling:
+
+```js
+import { normalizeListResult } from '@zeyos/client';
+
+const result = await client.api.listTickets({ filters: { visibility: 0 } });
+const { data: tickets } = normalizeListResult(result);
+```
+
+Use `normalizeCountResult()` for count-only requests.
+
+## Date and Timestamp Handling
+
+ZeyOS stores all dates as **Unix timestamps in seconds** (not milliseconds). When reading:
+
+```js
+// Convert to a JavaScript Date
+const date = new Date(ticket.duedate * 1000);
+
+// Format for display
+const label = new Date(ticket.duedate * 1000).toLocaleDateString(undefined, {
+  month: 'short', day: 'numeric', year: 'numeric',
+});
+
+// Check if overdue
+const isOverdue = ticket.duedate * 1000 < Date.now();
+```
+
+When writing (e.g. from an HTML `<input type="date">`):
+
+```js
+const dueDateVal = form.querySelector('#due-date').value; // '2026-03-15'
+const duedate = dueDateVal
+  ? Math.floor(new Date(dueDateVal).getTime() / 1000)
+  : null;
+
+await client.api.updateTicket({ ID: id, body: { duedate } });
+```
+
+## Selecting Fields for Performance
+
+Always pass a `fields` array in list requests. Without it, every field on every record is returned, which can significantly increase payload size and response time:
+
+```js
+// ✗ Returns all fields for every ticket
+const tickets = await client.api.listTickets({ limit: 500 });
+
+// ✓ Returns only what you need
+const tickets = await client.api.listTickets({
+  fields: ['ID', 'ticketnum', 'name', 'status', 'priority', 'duedate'],
+  filters: { visibility: 0 },
+  limit: 500,
+});
+```
+
+For single-record GET operations, field selection is not available — all standard fields are returned. Use query flags like `extdata: 1` and `tags: 1` to opt into additional data:
+
+```js
+const ticket = await client.api.getTicket({ ID: id, extdata: 1, tags: 1 });
+```
+
+## Optimistic UI Updates with Server Verification
+
+For immediate feedback on user actions (like drag-and-drop), apply the change to local state first, then confirm with the server and revert if it fails. Use the response body to confirm the actual resulting value:
+
+```js
+const fromStatus = ticket.status;
+
+// 1. Optimistic update — instant visual feedback
+ticket.status = toStatus;
+updateColumn(fromStatus);
+updateColumn(toStatus);
+
+try {
+  // 2. Send PATCH — response body contains the updated record
+  const updated = await client.api.updateTicket({
+    ID: ticket.ID,
+    body: { status: toStatus },
+  });
+
+  // 3. Confirm — use the server's value in case it was clamped or rejected
+  const confirmedStatus = updated?.status ?? toStatus;
+  if (confirmedStatus !== toStatus) {
+    ticket.status = confirmedStatus;
+    updateColumn(toStatus);
+    updateColumn(confirmedStatus);
+  }
+} catch (err) {
+  // 4. Revert on failure
+  ticket.status = fromStatus;
+  updateColumn(fromStatus);
+  updateColumn(toStatus);
+  showError(`Move failed: ${err.message}`);
+}
+```
+
+## Persisting Refreshed Tokens
+
+When using token mode with `autoRefresh: true` in a trusted environment, the client silently refreshes expired access tokens. The refreshed tokens are stored in the `MemoryTokenStore` but lost on page reload unless you persist them explicitly. Call a sync function after important API operations:
+
+```js
+async function syncTokens() {
+  try {
+    const ts = await client.auth.getTokenSet();
+    if (ts?.accessToken) {
+      localStorage.setItem('zeyos_tokens', JSON.stringify({
+        accessToken:           ts.accessToken,
+        refreshToken:          ts.refreshToken,
+        expiresAt:             ts.expiresAt,
+        refreshTokenExpiresAt: ts.refreshTokenExpiresAt,
+      }));
+    }
+  } catch {
+    // Non-critical — silently ignore
+  }
+}
+
+// Usage
+const tickets = await client.api.listTickets({ filters: { visibility: 0 } });
+await syncTokens(); // Persist any refreshed tokens
+```
+
+## Session Detection Without Tokens
+
+If you don't have an OAuth token but the user is already logged into ZeyOS in the same browser, you can detect their session via the userinfo endpoint:
+
+```js
+async function trySessionAuth(instanceUrl) {
+  try {
+    const res = await fetch(`${instanceUrl}oauth2/v1/userinfo`, {
+      credentials: 'include',
+    });
+    if (res.ok) return await res.json();
+  } catch {
+    // No session
+  }
+  return null;
+}
+
+const userInfo = await trySessionAuth('https://cloud.zeyos.com/demo/');
+if (userInfo) {
+  // Session is active — initialize in session mode
+  const client = createZeyosClient({
+    platform: instanceUrl,
+    auth: { mode: 'session', session: { enabled: true, credentials: 'include' } },
+  });
+}
+```
+
+:::note
+Session mode requires that your app is served from the same origin as ZeyOS, or that the ZeyOS instance is configured to allow cross-origin requests with credentials. If you are on a different domain, token mode is more reliable.
+:::
+
+## Navigating to ZeyOS Views
+
+To link users directly to a record inside the ZeyOS web interface, construct a URL in this format:
+
+```
+<INSTANCE_URL>?umi=<MODULE>&page=<PAGE>&id=<RECORD_ID>&tab=<TAB>
+```
+
+Common examples:
+
+```js
+const baseUrl = 'https://cloud.zeyos.com/demo/';
+
+// Link to a ticket
+`${baseUrl}?umi=tickets&page=details_ticket&id=${ticketId}&tab=0`
+
+// Link to a task (within the tickets module)
+`${baseUrl}?umi=tickets&page=details_ticket&id=${taskId}&tab=0`
+
+// Link to an account
+`${baseUrl}?umi=accounts&page=details_account&id=${accountId}&tab=0`
+```
+
+## Extended Data (extdata)
+
+Many ZeyOS entities support custom fields via `extdata`. These are returned as a nested object:
+
+```js
+// Request extended data in a list
+const tickets = await client.api.listTickets({
+  fields: ['ID', 'name', 'extdata.region', 'extdata.customer_type'],
+  filters: { visibility: 0 },
+});
+
+// Or include all extdata for single-record fetches
+const ticket = await client.api.getTicket({ ID: id, extdata: 1 });
+console.log(ticket.extdata); // { region: 'EMEA', customer_type: 'Enterprise', ... }
+```
+
+When saving extended data back, pass it as a plain object:
+
+```js
+await client.api.updateTicket({
+  ID: id,
+  body: {
+    extdata: { region: 'APAC', customer_type: 'SMB' },
+  },
+});
+```
+
+## Common Status and Priority Values
+
+Ticket and task status and priority values are plain integers. The canonical values observed in the ZeyOS API:
+
+### Ticket Status
+
+| Value | Label |
+|-------|-------|
+| `0` | Not Started |
+| `1` | Awaiting Acceptance |
+| `2` | Accepted |
+| `3` | Rejected |
+| `4` | Active |
+| `5` | Inactive |
+| `6` | Feedback Required |
+| `7` | Testing |
+| `8` | Cancelled |
+| `9` | Completed |
+| `10` | Failed |
+| `11` | Booked |
+
+### Ticket Priority
+
+| Value | Label |
+|-------|-------|
+| `0` | Lowest |
+| `1` | Low |
+| `2` | Medium |
+| `3` | High |
+| `4` | Highest |
+
+## Error Handling Checklist
+
+`ZeyosApiError` is thrown for all non-2xx responses. Key properties to check:
+
+```js
+import { ZeyosApiError } from '@zeyos/client';
+
+try {
+  await client.api.updateTicket({ ID: id, body: data });
+} catch (err) {
+  if (!(err instanceof ZeyosApiError)) throw err; // Re-throw unexpected errors
+
+  if (err.status === 401) {
+    // Session expired or token invalid — redirect to login
+  } else if (err.status === 403) {
+    // Insufficient permissions
+  } else if (err.status === 404) {
+    // Record does not exist
+  } else if (err.status === 409) {
+    // Conflict — record was modified since last read (check If-Match header usage)
+  } else {
+    // Generic error — err.body often contains a human-readable message
+    console.error(err.body?.message ?? err.message);
+  }
+}
+```
+
+:::tip
+On 401, the client automatically retries with a refreshed token if `autoRefresh: true` is set, a refresh token is available, and OAuth client credentials are configured. You will only see a 401 error if the refresh also fails — typically meaning the user's session has fully expired.
+:::

package/docs/02-javascript-client/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "JavaScript Client",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "description": "The ZeyOS JavaScript client: installation, authentication, CRUD operations, and real-world implementation patterns."
+  }
+}

package/docs/03-cli/01-getting-started.md

@@ -0,0 +1,219 @@
+---
+sidebar_label: Getting Started
+---
+
+# CLI Getting Started
+
+The ZeyOS CLI gives you fast, scriptable access to the ZeyOS REST API from your terminal. It is the default entry point for coding agents and shell automation against the CLI's curated resource registry.
+
+## Installation
+
+:::info Requirements
+Node.js 18.3+ is required. The CLI has zero external dependencies beyond the bundled `@zeyos/client` package.
+:::
+
+### Published package (recommended)
+
+Install the CLI globally from npm:
+
+```bash
+npm install -g @zeyos/cli
+zeyos --help
+```
+
+### Running from source
+
+If you are contributing to the CLI or need to run an unreleased version, clone the repository and run directly from the source tree:
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd client
+
+# Run directly
+./cli/bin/zeyos.mjs --help
+```
+
+For convenience, create a symlink so you can run `zeyos` from anywhere:
+
+```bash
+ln -s $(pwd)/cli/bin/zeyos.mjs /usr/local/bin/zeyos
+```
+
+## First Login
+
+Authenticate with your ZeyOS instance using the `login` command:
+
+```bash
+# Interactive — prompts for URL, app ID, and secret
+zeyos login
+
+# Or provide all values upfront
+zeyos login \
+  --base-url https://cloud.zeyos.com/demo \
+  --client-id myapp \
+  --secret "$ZEYOS_CLIENT_SECRET"
+```
+
+For interactive use, omit `--secret`; the CLI prompts without echoing the secret to the terminal. Passing secrets as command-line arguments is best reserved for controlled automation.
+
+**What happens:**
+
+1. The CLI opens your browser to the ZeyOS authorization page
+2. You log in and authorize the application
+3. The CLI exchanges the authorization code for access + refresh tokens
+4. Credentials are saved to `.zeyos/auth.json` in your project
+
+:::tip Switching Instances
+Use `--clean` to discard all saved credentials and start fresh:
+```bash
+zeyos login --clean
+```
+This is useful when switching between ZeyOS instances.
+:::
+
+## Your First Commands
+
+Once logged in, you can start working with your data:
+
+```bash
+# Check who you're logged in as
+zeyos whoami
+
+# List tickets (table output by default)
+zeyos list tickets
+
+# Get a specific ticket with all details
+zeyos get ticket 42 --all
+
+# Count records
+zeyos count accounts
+
+# Create a new ticket
+zeyos create ticket --name "Fix login bug" --status 0 --priority 3
+
+# Update a ticket's status
+zeyos update ticket 42 --status 4
+
+# Delete a ticket
+zeyos delete ticket 42
+```
+
+Inspect the curated CLI-supported resource set at any time:
+
+```bash
+zeyos resources
+```
+
+If the resource you need does not appear there, switch to [`@zeyos/client`](../02-javascript-client/01-getting-started.md).
+
+## Discover the Schema
+
+Inspect a resource's fields, types, foreign keys, and enum values before querying. This works offline -- no login required -- so it is a fast way to learn the data model:
+
+```bash
+zeyos describe tickets
+zeyos describe accounts --json
+```
+
+## Install Agent Skills
+
+If you are driving the CLI from a coding agent (Claude, Codex, …), install the bundled ZeyOS skill packs into your project so the agent picks up the right query conventions:
+
+```bash
+zeyos skills list                 # see the available skills
+zeyos skills install              # copy them into .claude/skills (or .codex)
+```
+
+See the [Commands Reference](./02-commands.md#skills) for details.
+
+## Working with Filters
+
+Query specific records using JSON filter expressions:
+
+```bash
+# Tickets with status = 1 (In Progress)
+zeyos list tickets --filter '{"status":1}'
+
+# Combine multiple criteria (AND logic)
+zeyos list tickets --filter '{"status":1,"priority":3}'
+
+# Count matching records
+zeyos count tickets --filter '{"status":1}'
+```
+
+For normal operational views, include `visibility: 0`:
+
+```bash
+zeyos list tickets --filter '{"visibility":0,"status":1}'
+```
+
+## Sorting and Pagination
+
+```bash
+# Sort by name ascending, then by last modified descending
+zeyos list tickets --sort "+name,-lastmodified"
+
+# Limit results and paginate
+zeyos list tickets --limit 10
+zeyos list tickets --limit 10 --offset 10   # page 2
+```
+
+When results fill the page limit, the CLI automatically shows pagination info:
+
+```
+Showing 1–10 of 47  (--offset 10 for next page)
+```
+
+## Output Formats
+
+Choose the format that fits your workflow:
+
+```bash
+# Default: formatted table (human-readable)
+zeyos list tickets
+
+# JSON: for scripting and piping
+zeyos list tickets --json
+
+# YAML: for config-friendly output
+zeyos list tickets --yaml
+```
+
+:::tip Piping
+JSON output works great with tools like `jq`:
+```bash
+zeyos list tickets --json | jq '.[].name'
+```
+:::
+
+## JSON-First Automation
+
+For coding agents and non-interactive scripts, prefer `--json` output and JSON-first writes:
+
+```bash
+zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3,"visibility":0}' --json
+zeyos update ticket 42 --data '{"status":4}' --json
+```
+
+`zeyos whoami --json` does not print access tokens. If a local tool explicitly needs the current token, use `zeyos whoami --show-token --json` and treat the output as a secret.
+
+## Credential Storage
+
+Tokens are saved to `.zeyos/auth.json` in your project directory (or the nearest parent that has one). For global credentials shared across projects:
+
+```bash
+zeyos login --global
+```
+
+This saves to `~/.config/zeyos/credentials.json` instead.
+
+:::warning
+Add `.zeyos/auth.json` to your `.gitignore` — it contains access tokens.
+:::
+
+## Next Steps
+
+- **[Coding Agents](../04-agent-workflows/00-coding-agents.md)** -- CLI-first workflows and escalation guidance
+- **[Commands Reference](./02-commands.md)** — Full reference for every command
+- **[Configuration](./03-configuration.md)** — Config files, environment variables, and resource field customization