@zeyos/client 0.2.0 → 0.3.0

package/docs/02-javascript-client/03-making-requests.md

@@ -253,6 +253,26 @@ const page2 = await client.api.listTickets({
 Use `count: true` to get the total number of matching records without fetching the full dataset. This is useful for building pagination controls.
 :::
 
+### Auto-pagination
+
+To iterate an entire result set without managing `offset` yourself, use `client.paginate(operationId, input, opts)` — an async iterator that pages until a short/empty page (or `opts.max`) is reached. It removes the off-by-one and "I only got the first 1000 / 50 rows" mistakes the list caps otherwise invite.
+
+```js
+// Stream every matching ticket, one page at a time
+for await (const ticket of client.paginate('listTickets', { filters: { visibility: 0 } }, { pageSize: 1000 })) {
+  process(ticket);
+}
+
+// Eagerly collect up to a cap
+const recent = await client.collect(
+  'listTickets',
+  { filters: { visibility: 0 }, sort: ['-lastmodified'] },
+  { pageSize: 500, max: 2000 }
+);
+```
+
+`opts`: `pageSize` (default 1000, clamped to the server max of 10000), `max` (stop after N records), and `requestOptions` (forwarded to each underlying call, e.g. `{ signal, timeoutMs }`). `collect` is the eager array form of `paginate`.
+
 ## Normalising List Responses
 
 List endpoints are not uniform across the full surface area. Depending on the endpoint and response mode, you may see:
@@ -432,9 +452,32 @@ const noRetry = createZeyosClient({ platform: 'live', instance: 'demo', retry: f
 Only `429`/`503` are retried by default -- statuses that clearly mean "try again later". `5xx` codes such as `500`/`502` are **not** retried automatically, to avoid re-applying a non-idempotent write that may have partially succeeded. Add them to `retryOn` only for read-heavy workloads.
 :::
 
+### Request timeout
+
+A request with no built-in deadline can hang indefinitely if the connection stalls (e.g. an instance restarting). Set `timeoutMs` to bound each attempt; it composes with any `AbortSignal` you pass. The timeout applies **per attempt**, so a retry gets a fresh deadline.
+
+```js
+// Per request
+await client.api.listTickets({ filters: { visibility: 0 } }, { timeoutMs: 8000 });
+
+// Or a client-wide default
+const client = createZeyosClient({ platform: 'live', instance: 'demo', timeoutMs: 8000 });
+```
+
+A timeout rejects with an `Error` whose `isTimeout === true` (and `code === 'ETIMEDOUT'`). A timeout is distinct from a caller abort: aborting your own `AbortSignal` always propagates immediately and is never retried.
+
+### Network-error retries
+
+Network-level failures (a dropped connection, DNS blip, or a timeout) are retried for **read** operations only — `GET`/`HEAD` plus side-effect-free `list`/`count`/`search` queries — using the same retry budget and backoff. Writes (`create`/`update`/`delete`) are **never** auto-retried on a network error, so a dropped connection can't cause a duplicate mutation. Override per request or per client with `retryOnNetworkError: true | false`.
+
+```js
+await client.api.listTickets({ filters: {} }, { retryOnNetworkError: true });  // force (already on for reads)
+await client.api.createTicket({ name: 'x' }, { retryOnNetworkError: true });   // opt a write in, at your own risk
+```
+
 ## Error Handling
 
-All API errors are thrown as `ZeyosApiError` instances. This class extends `Error` and includes structured information about the failed request.
+All API errors are thrown as `ZeyosApiError` instances. This class extends `Error` and includes structured information about the failed request. When the server returns an error body with a message, a short snippet of it is folded into `err.message` (e.g. `api.listTickets failed with HTTP 400: unknown filter field: bogus`), so the thrown error says *why*, not just the status code. The full body is always on `err.body`.
 
 ```js
 import { ZeyosApiError } from '@zeyos/client';
@@ -535,6 +578,8 @@ All generated methods and `client.request()` accept an optional second argument
 | Option | Type | Description |
 |--------|------|-------------|
 | `signal` | `AbortSignal` | An `AbortController` signal to cancel the request |
+| `timeoutMs` | `number` | Abort this attempt after N ms (composes with `signal`); also settable client-wide as `timeoutMs` |
+| `retryOnNetworkError` | `boolean` | Force/disable retrying network errors & timeouts for this call (default: on for reads, off for writes) |
 | `raw` | `boolean` | Return the full response envelope instead of just the data |
 | `auth` | `string \| { mode?: string, accessToken?: string, access_token?: string, refreshToken?: string, refresh_token?: string, clientId?: string, client_id?: string, clientSecret?: string, client_secret?: string }` | Override the authentication mode or credentials for this request |
 | `baseUrl` | `string` | Override the base URL for this request |

package/docs/03-cli/02-commands.md

@@ -14,6 +14,7 @@ These options work with any command:
 |--------|-------------|
 | `--json` | Output as formatted JSON |
 | `--yaml` | Output as YAML |
+| `--profile <name>` | Use a named credential profile for this command |
 | `--no-color` | Disable ANSI color output |
 | `-h`, `--help` | Show help for a command |
 
@@ -101,6 +102,36 @@ zeyos whoami --show-token --json   # explicitly include the current access token
 
 ---
 
+## profile
+
+Manage named credential profiles and switch between ZeyOS instances. See [Configuration → Profiles](./03-configuration.md#profiles) for the full model.
+
+```
+zeyos profile <list|current|use|add|remove> [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `profile list` | List all profiles; the active one is marked `*`, with token status |
+| `profile current` | Show which profile resolves right now, and why (flag/env/pin/active) |
+| `profile use <name>` | Make `<name>` the active profile (global) |
+| `profile use <name> --local` | Pin `<name>` to the current project (`.zeyos/profile`) |
+| `profile add <name> [opts]` | Create/update a profile (`--base-url`, `--client-id`, `--secret`, or `--from-current`) |
+| `profile remove <name>` | Delete a profile |
+
+**Examples:**
+
+```bash
+zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
+zeyos profile add prod --from-current        # snapshot current credentials
+zeyos login --profile prod                   # authenticate into & activate a profile
+zeyos profile use dev                         # switch active profile
+zeyos profile use prod --local                # pin to this project
+zeyos list tickets --profile dev              # one-off override on any command
+```
+
+---
+
 ## list
 
 Query and list records for a resource with filtering, sorting, and pagination.
@@ -363,7 +394,10 @@ List all curated CLI resources and their operations. This is the authoritative b
 zeyos resources
 ```
 
-Shows a table of all CLI-supported resource types and available operations.
+Shows a table of all CLI-supported resource types and available operations. Operational
+workflows can use `actionstep` / `actionsteps` / `time-entries` for follow-ups and
+effort records. Read-only platform schema definitions are available as `customfield` /
+`customfields` with `list`, `get`, and therefore `count` support.
 
 ---
 

package/docs/03-cli/03-configuration.md

@@ -12,15 +12,47 @@ These settings apply to the CLI's curated resource registry. If you need a resou
 
 ## Credential Cascade
 
-Credentials are resolved from three sources in priority order:
+The CLI first decides **which credential set** is the base, then lets environment credential variables field-override on top. The base is chosen by the first match in this order:
 
 | Priority | Source | Location |
 |----------|--------|----------|
-| 1 (highest) | Environment variables | `ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, etc. |
-| 2 | Local config file | `.zeyos/auth.json` (walks up from CWD) |
-| 3 (lowest) | Global config file | `~/.config/zeyos/credentials.json` |
+| 1 (highest) | `--profile <name>` flag | named profile (per command) |
+| 2 | `ZEYOS_PROFILE` env var | named profile |
+| 3 | Project pin | `.zeyos/profile` (walks up from CWD) |
+| 4 | Local config file | `.zeyos/auth.json` (walks up from CWD) |
+| 5 | Global active profile | `~/.config/zeyos/profiles.json` (`active`) |
+| 6 (lowest) | Global config file | `~/.config/zeyos/credentials.json` |
 
-Configuration is merged from global, then local, then environment variables. Higher-priority sources override individual fields from lower-priority sources. For example, setting `ZEYOS_TOKEN` as an environment variable overrides the stored token while still allowing `baseUrl` and client credentials to come from a config file.
+On top of the chosen base, the credential **environment variables** (`ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, …) always override individual fields — so you can keep `baseUrl` and client credentials in a profile while overriding just the token via `ZEYOS_TOKEN` in CI.
+
+If you have never created a profile, nothing changes: the CLI falls through to the legacy local `.zeyos/auth.json` and global `credentials.json` exactly as before.
+
+## Profiles
+
+Profiles let you store several ZeyOS instances (e.g. `dev`, `prod`, `client-x`) and switch between them without re-running `login`. Each profile is a full credential set (URL, OAuth app, tokens) kept in `~/.config/zeyos/profiles.json`, with one marked **active**.
+
+```bash
+# Create profiles (connection params now; tokens via login)
+zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
+zeyos profile add prod --base-url https://cloud.zeyos.com/acme --client-id app --secret "$SECRET"
+
+# Authenticate into a profile (also makes it active)
+zeyos login --profile prod
+
+# See and switch profiles
+zeyos profile list                 # active marked with *, shows token status
+zeyos profile use dev              # switch the global active profile
+zeyos profile current             # what resolves right now, and why
+
+# Per-project: pin a profile so cd-ing into a repo selects its instance
+cd ~/work/acme && zeyos profile use prod --local   # writes ./.zeyos/profile
+
+# One-off override on any command (beats env, pin, and active)
+zeyos whoami --profile dev
+zeyos list tickets --profile prod
+```
+
+`zeyos profile add <name> --from-current` snapshots whatever credentials are in effect (including tokens) into a new profile — handy for adopting an existing `.zeyos/auth.json` setup. Add `.zeyos/profile` to `.gitignore` alongside `.zeyos/auth.json`.
 
 ## Environment Variables
 

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

@@ -107,6 +107,28 @@ Count matching records:
 
 ```bash
 zeyos count tickets --filter '{"visibility":0,"status":4}' --json
+zeyos count customfields --json
+zeyos count actionsteps --filter '{"status":0}' --json
+```
+
+Summarize actionstep effort/time-entry evidence:
+
+```bash
+zeyos list actionsteps \
+  --fields ID,name,status,date,duedate,effort,ticket,task,account \
+  --filter '{"status":3}' \
+  --limit 100 \
+  --json
+```
+
+Inspect ticket-linked mail without sending anything:
+
+```bash
+zeyos list messages \
+  --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference,messageid \
+  --filter '{"ticket":42}' \
+  --sort +date \
+  --json
 ```
 
 ## Write Data
@@ -145,4 +167,6 @@ zeyos delete ticket 42 --force
 - 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.
+- Use `actionsteps.effort` for time-entry totals; do not infer booked time from task assignment.
+- Draft e-mail text in the response unless the user explicitly asks for a real ZeyOS draft record; never send mail from an agent workflow.
 - Escalate to [`@zeyos/client`](./03-cli-coverage-and-escalation.md) when the CLI resource registry is not enough.

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

@@ -13,10 +13,11 @@ The command `zeyos resources` is the source of truth for CLI-supported resource
 
 | 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` |
+| `account`, `actionstep`, `appointment`, `campaign`, `contact`, `document`, `event`, `file`, `invitation`, `item`, `message`, `note`, `opportunity`, `payment`, `project`, `storage`, `task`, `ticket`, `transaction` | `list`, `get`, `create`, `update`, `delete` |
+| `customfield` / `customfields` | `list`, `get` |
 | `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.
+Plural names and common aliases such as `tickets`, `actionsteps`, `time-entries`, `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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",
@@ -34,9 +34,6 @@
     "samples/crm",
     "samples/dashboard",
     "samples/kanban",
-    "samples/missioncontrol/README.md",
-    "samples/missioncontrol/fetch-data.mjs",
-    "samples/missioncontrol/index.html",
     "agents",
     "README.md",
     "CHANGELOG.md",

package/src/runtime/client.js

@@ -56,8 +56,14 @@ function abortableDelay(ms, signal) {
   });
 }
 
-// Honor a Retry-After header (seconds or HTTP-date), else exponential backoff
-// with jitter, capped at maxDelayMs.
+// Exponential backoff with jitter, capped at maxDelayMs.
+function backoffDelay(attempt, retryConfig) {
+  const exp = retryConfig.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * retryConfig.baseDelayMs;
+  return Math.min(retryConfig.maxDelayMs, exp + jitter);
+}
+
+// Honor a Retry-After header (seconds or HTTP-date), else exponential backoff.
 function computeRetryDelay(response, attempt, retryConfig) {
   const header = response.headers?.['retry-after'];
   // An empty or whitespace-only header carries no delay directive — `Number('')`
@@ -74,9 +80,88 @@ function computeRetryDelay(response, attempt, retryConfig) {
       return Math.min(retryConfig.maxDelayMs, Math.max(0, dateMs - Date.now()));
     }
   }
-  const exp = retryConfig.baseDelayMs * Math.pow(2, attempt);
-  const jitter = Math.random() * retryConfig.baseDelayMs;
-  return Math.min(retryConfig.maxDelayMs, exp + jitter);
+  return backoffDelay(attempt, retryConfig);
+}
+
+// Operations that are safe to transparently retry on a network error / timeout:
+// HTTP GET/HEAD, plus ZeyOS read queries (list/count/search) which are POST but
+// side-effect-free. Writes (create/update/delete) are never auto-retried, so a
+// dropped connection can't cause a duplicate mutation.
+function isReadOperation(operation) {
+  const method = operation?.method;
+  if (method === 'GET' || method === 'HEAD') {
+    return true;
+  }
+  return /^(list|count|search|exists|get)/i.test(operation?.operationId || '');
+}
+
+// Build a one-line, human-readable summary from a server error body so the thrown
+// error message says *why* (e.g. an unknown-filter 400), not just the status code.
+// The full body remains available on error.body.
+function summarizeErrorBody(body, maxLength = 200) {
+  let text = '';
+  if (typeof body === 'string') {
+    text = body.trim();
+  } else if (body && typeof body === 'object') {
+    const candidate =
+      body.message ?? body.error_description ?? body.error ?? body.detail ?? body.title;
+    if (typeof candidate === 'string' && candidate.trim()) {
+      text = candidate.trim();
+    } else {
+      try {
+        text = JSON.stringify(body);
+      } catch {
+        text = '';
+      }
+    }
+  }
+  if (!text) {
+    return '';
+  }
+  return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+}
+
+// Run fetch with an optional per-attempt timeout, composed with the caller's
+// AbortSignal (Node 18 compatible — no AbortSignal.any). A timeout aborts the
+// internal controller only, so `externalSignal.aborted` stays false and the
+// caller can distinguish a timeout (retryable for reads) from a user abort.
+async function fetchWithTimeout(httpRequestImpl, requestArgs, externalSignal, timeoutMs) {
+  if (!(timeoutMs > 0)) {
+    return httpRequestImpl({ ...requestArgs, signal: externalSignal });
+  }
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const onExternalAbort = () => controller.abort(externalSignal.reason);
+
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort(externalSignal.reason);
+    } else {
+      externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+    }
+  }
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    return await httpRequestImpl({ ...requestArgs, signal: controller.signal });
+  } catch (error) {
+    if (timedOut) {
+      const timeoutError = new Error(`Request timed out after ${timeoutMs}ms`);
+      timeoutError.name = 'TimeoutError';
+      timeoutError.code = 'ETIMEDOUT';
+      timeoutError.isTimeout = true;
+      throw timeoutError;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    externalSignal?.removeEventListener?.('abort', onExternalAbort);
+  }
 }
 
 const AUTH_SCHEME_MAP = Object.freeze({
@@ -390,7 +475,8 @@ function chooseBodyType(serviceKey, operation, prepared, fallbackBodyType) {
 
 function createApiError(response, { serviceKey, operation, method, url }) {
   const operationDescription = operation.operationId ? `${serviceKey}.${operation.operationId}` : `${serviceKey} request`;
-  const message = `${operationDescription} failed with HTTP ${response.status}`;
+  const detail = summarizeErrorBody(response.data);
+  const message = `${operationDescription} failed with HTTP ${response.status}${detail ? `: ${detail}` : ''}`;
 
   return new ZeyosApiError(message, {
     status: response.status,
@@ -606,6 +692,10 @@ export function createZeyosClient(rawConfig = {}) {
 
   const defaultHeaders = isObject(config.headers) ? config.headers : {};
   const retryConfig = normalizeRetry(config.retry);
+  const defaultTimeoutMs = Number(config.timeoutMs) > 0 ? Number(config.timeoutMs) : 0;
+  // Whether to transparently retry network errors / timeouts. `undefined` (default)
+  // means "auto": retry only read operations. `true`/`false` force the behavior.
+  const defaultRetryOnNetworkError = typeof config.retryOnNetworkError === 'boolean' ? config.retryOnNetworkError : undefined;
   const schemaApi = createSchema({ services: SERVICES, schema: SCHEMA });
   const validateByDefault = config.validate === true;
   const operationLookup = new Map();
@@ -616,6 +706,10 @@ export function createZeyosClient(rawConfig = {}) {
     }
   }
 
+  // Single-flight token refresh: shared across all concurrent operations so an
+  // expired token triggers exactly one getToken call (see refreshAccessTokenOnce).
+  let refreshInFlight = null;
+
   async function getTokenSet() {
     return normalizeTokenSet(await tokenStore.get());
   }
@@ -644,6 +738,15 @@ export function createZeyosClient(rawConfig = {}) {
     return `ZEYOSID=${cookieValue}`;
   }
 
+  // Resolve whether a network error / timeout may be retried for this call.
+  // Explicit per-request / client config wins; otherwise auto = read ops only.
+  function resolveNetworkRetry(operation, requestOptions) {
+    const explicit = requestOptions?.retryOnNetworkError ?? defaultRetryOnNetworkError;
+    if (explicit === true) return true;
+    if (explicit === false) return false;
+    return isReadOperation(operation);
+  }
+
   async function sendRequestOnce({ serviceKey, operation, prepared, requestAuth, tokenSet, candidate, requestOptions }) {
     const body = cloneValue(prepared.body);
     const authHeaders = {};
@@ -698,19 +801,27 @@ export function createZeyosClient(rawConfig = {}) {
     );
 
     const signal = prepared.signal ?? requestOptions?.signal;
+    const timeoutMs = Number(requestOptions?.timeoutMs ?? defaultTimeoutMs) || 0;
+    const networkRetryAllowed = resolveNetworkRetry(operation, requestOptions);
+    const requestArgs = { fetchImpl, url, method: operation.method, headers, body, bodyType, credentials };
 
     let response;
     for (let attempt = 0; ; attempt++) {
-      response = await httpRequest({
-        fetchImpl,
-        url,
-        method: operation.method,
-        headers,
-        body,
-        bodyType,
-        signal,
-        credentials
-      });
+      try {
+        response = await fetchWithTimeout(httpRequest, requestArgs, signal, timeoutMs);
+      } catch (error) {
+        // A caller-initiated abort must never be retried — propagate immediately.
+        // (A timeout aborts only the internal controller, so signal.aborted is false.)
+        if (signal?.aborted) {
+          throw error;
+        }
+        // Network error or timeout: retry only safe (read) operations, within budget.
+        if (!networkRetryAllowed || attempt >= retryConfig.maxRetries) {
+          throw error;
+        }
+        await abortableDelay(backoffDelay(attempt, retryConfig), signal);
+        continue;
+      }
 
       if (attempt >= retryConfig.maxRetries || !retryConfig.retryOn.has(response.status)) {
         break;
@@ -787,6 +898,22 @@ export function createZeyosClient(rawConfig = {}) {
     return nextTokenSet;
   }
 
+  // Single-flight wrapper: when several operations notice an expired token at the
+  // same time (e.g. `Promise.all([...])`), they must share ONE refresh. Without
+  // this each fires its own getToken — redundant load, and a hard failure when the
+  // server rotates refresh tokens (all but the first present a stale refresh token).
+  function refreshAccessTokenOnce(currentTokenSet, requestAuth, requestOptions) {
+    if (refreshInFlight) {
+      return refreshInFlight;
+    }
+    refreshInFlight = Promise.resolve()
+      .then(() => refreshAccessToken(currentTokenSet, requestAuth, requestOptions))
+      .finally(() => {
+        refreshInFlight = null;
+      });
+    return refreshInFlight;
+  }
+
   async function executeOperation({ serviceKey, operation, prepared, requestOptions = {} }) {
     // Dry run: resolve the route + payload exactly as they would be sent, but
     // return that descriptor instead of performing any network request or token
@@ -826,7 +953,7 @@ export function createZeyosClient(rawConfig = {}) {
       canRefreshAccessToken({ mode, operation, tokenSet, oauthConfig })
     ) {
       try {
-        const refreshed = await refreshAccessToken(tokenSet, requestAuth, requestOptions);
+        const refreshed = await refreshAccessTokenOnce(tokenSet, requestAuth, requestOptions);
         if (refreshed?.accessToken) {
           tokenSet = refreshed;
         }
@@ -865,7 +992,7 @@ export function createZeyosClient(rawConfig = {}) {
 
         if (candidate.type === 'bearer' && canRefreshAccessToken({ mode, operation, tokenSet, oauthConfig })) {
           try {
-            const refreshed = await refreshAccessToken(tokenSet, requestAuth, requestOptions);
+            const refreshed = await refreshAccessTokenOnce(tokenSet, requestAuth, requestOptions);
             if (refreshed?.accessToken) {
               tokenSet = refreshed;
               const retryResponse = await sendRequestOnce({
@@ -1017,6 +1144,58 @@ export function createZeyosClient(rawConfig = {}) {
   const oauth2Operations = bindService('oauth2');
   const legacyAuth = bindService('legacyAuth');
 
+  // Async-iterate every record from a list operation, paging by `offset` until a
+  // short/empty page (or `opts.max`) is reached — removing the manual offset
+  // bookkeeping the 1000/10000 list caps otherwise force on callers.
+  //
+  //   for await (const ticket of client.paginate('listTickets', { filters: { visibility: 0 } })) { … }
+  //
+  async function* paginate(operationId, input = {}, opts = {}) {
+    const op = operationLookup.get(`api.${operationId}`);
+    if (!op) {
+      const candidates = (SERVICES.api?.operations ?? []).map((entry) => entry.operationId);
+      const suggestion = suggestClosest(operationId, candidates);
+      throw new ZeyosApiError(
+        `Unknown list operation: api.${operationId}.` + (suggestion ? ` Did you mean '${suggestion}'?` : ''),
+        { operationId, service: 'api' }
+      );
+    }
+
+    const requested = Number(opts.pageSize) > 0 ? Number(opts.pageSize)
+      : Number(input.limit) > 0 ? Number(input.limit) : 1000;
+    // Clamp to the server's max page size: a larger request would be silently
+    // capped server-side, making the short-page terminator stop early and drop rows.
+    const pageSize = Math.min(requested, 10000);
+    const max = Number(opts.max) > 0 ? Number(opts.max) : Infinity;
+    let offset = Number(input.offset) > 0 ? Number(input.offset) : 0;
+    let yielded = 0;
+
+    for (;;) {
+      const page = await api[operationId]({ ...input, limit: pageSize, offset }, opts.requestOptions);
+      const rows = Array.isArray(page) ? page : Array.isArray(page?.data) ? page.data : [];
+      for (const row of rows) {
+        yield row;
+        yielded += 1;
+        if (yielded >= max) {
+          return;
+        }
+      }
+      if (rows.length < pageSize) {
+        return; // last (short or empty) page
+      }
+      offset += pageSize;
+    }
+  }
+
+  // Eager convenience: collect up to `opts.max` records into an array.
+  async function collect(operationId, input = {}, opts = {}) {
+    const out = [];
+    for await (const row of paginate(operationId, input, opts)) {
+      out.push(row);
+    }
+    return out;
+  }
+
   function buildAuthorizationUrl(options = {}) {
     const clientId = options.clientId ?? options.client_id ?? oauthConfig.clientId;
     const redirectUri = options.redirectUri ?? options.redirect_uri;
@@ -1219,6 +1398,8 @@ export function createZeyosClient(rawConfig = {}) {
     oauth2,
     legacyAuth,
     request,
+    paginate,
+    collect,
     schema: schemaApi,
     auth: {
       getTokenSet,

package/samples/missioncontrol/README.md

@@ -1,106 +0,0 @@
-# Mission Control
-
-A team-performance dashboard for an IT consultancy running on ZeyOS — built on
-the [`@zeyos/client`](../../README.md) library. It answers the managing
-director's question: **who is actually working, and where is there untapped
-capacity?**
-
-A dark "mission control" view: a velocity KPI row, a 13-week throughput trend,
-a team-capacity strip, and a searchable/sortable/filterable grid of per-employee
-activity cards (click one for a per-type digest + contribution graph).
-
-## What it shows
-
-1. **Velocity** — tickets opened vs closed in the window, net flow, average /
-   median / p90 **cycle time** (open → close), open backlog (with overdue), and
-   total **hours booked**. A 13-week **throughput trend** of opened vs closed.
-2. **Activity card per employee** — open tickets, open tasks, tickets closed,
-   hours booked, a weekly-hours sparkline, team/location tags, a **capacity
-   badge** (Overloaded / Balanced / Available / Idle / Former), and **last
-   activity** (the most recent time entry) — flagged red when it's **older than
-   7 days**. Hover "last activity" to see the engineer's **last 10 time entries**
-   (date · type · customer · ticket · hours).
-3. **Per-employee digest** (click a card) — **booked hours stacked by
-   `extdata.type`** (Weekly / Monthly), and a **GitHub-style contribution graph**
-   of their time-entry activity over the last 53 weeks.
-
-Filters: search by name, **filter by team / department / location** (group
-membership), capacity chips (Engaged / Spare capacity / Inactive >7d /
-Overloaded / All), and sort by activity, hours, throughput, workload, cycle,
-overdue, or least-recent.
-
-The **Team capacity** strip and the *Spare capacity* filter surface the
-"untapped resources": active engineers running light or with no load at all,
-contrasted with the overloaded ones — the clearest place to rebalance work.
-
-## Run it
-
-```bash
-# 1. Authenticate once (if you haven't already)
-zeyos login --base-url https://zeyos.cms-it.de/dev
-
-# 2. Pull live data into data.js (read-only; reuses your CLI credentials)
-node samples/missioncontrol/fetch-data.mjs            # 90-day window
-node samples/missioncontrol/fetch-data.mjs --days 180 # custom window
-
-# 3. Open the dashboard
-#    Either open index.html directly, or serve the folder:
-python3 -m http.server 8765 --directory samples/missioncontrol
-#    → http://localhost:8765
-```
-
-`fetch-data.mjs` writes `data.js` (a `window.MISSION_DATA = …` assignment) so
-`index.html` works straight from disk — no server, no CORS, no token pasting.
-Re-run the fetcher to refresh; the page is otherwise a static, dependency-free
-single file (hand-rolled CSS + inline-SVG charts).
-
-## How it works
-
-`fetch-data.mjs` reads the credentials `zeyos login` stored
-(`.zeyos/auth.json` or `~/.config/zeyos/credentials.json`), builds an
-auto-refreshing client with `createZeyosClient`, and issues a handful of
-**read-only** `list` queries (tickets, `actionsteps`, tasks, groups), then
-aggregates them client-side (ZeyOS has no server-side group-by). It never writes
-to ZeyOS.
-
-### Metric definitions (so the numbers are reproducible)
-
-| Metric | Definition |
-|--------|------------|
-| **Time entry** | an `actionsteps` row with `status IN [1, 3]` (COMPLETED + BOOKED), attributed to an engineer via **`assigneduser`** (`owneruser` is unused here). `effort` is in **minutes**. |
-| **Last activity** | the engineer's most recent time-entry `date`; **stale** (red ⚠) when it's >7 days before the "as of" date. |
-| **Type** | `extdata.type` of each time entry (Intern / Auftrag / Consulting / Wartung / …), selected on `list` via the `extdata.type` field. Top 6 are charted; the rest roll into *Other*. |
-| **Closed / done** | tickets with `status IN [9, 11]` — COMPLETED + BOOKED (BOOKED, completed & billed, is the dominant terminal state). |
-| **Open backlog** | `status IN [0, 1, 2, 4, 6, 7]` — started/accepted/active but not done. |
-| **Opened in window** | tickets whose indexed `date` falls in the window. |
-| **Cycle time** | `lastmodified − creationdate` for tickets closed in the window (a proxy for the close timestamp, which ZeyOS does not store separately). |
-| **Capacity** | relative to the engaged-and-active cohort: *overloaded* (top-quintile workload or ≥3 overdue), *available* (low workload **and** below-median throughput), *idle* (active user, zero load), *balanced* (else), *former* (deactivated user with leftover assignments). |
-| **Team / location** | the engineer's **group memberships** (see below). |
-
-### Notes & limitations
-
-- **Department/location = groups.** ZeyOS *defines* custom fields
-  `users.department`/`users.location`/`users.team`, but the API returns
-  *"Extension data not available for users"* — they can't be read. The org
-  structure instead lives in **group membership** (e.g. `Developers`,
-  `Services`, `Technik`, `Berlin`, `Bayern`, `Nordrhein-Westfalen`), which is
-  what the team/location filter uses.
-- **`extdata` only lists via dot-fields.** Custom fields aren't returned by a
-  plain `list` (or `extdata=1`); they must be selected explicitly, e.g.
-  `fields: ['…','extdata.type']` (returned as `extdata_type`). On single records
-  `getTicket(…, { query:{ extdata:1 } })` returns them under an `extdata` object.
-- **Corrupt time-entry dates.** Many `actionsteps` have far-future `date` values
-  (year 2099+); the fetcher bounds queries to `date ≤ now` to exclude them.
-- **"As of" anchoring.** Windows are measured back from the latest activity in
-  the data, not wall-clock today — so a frozen/dev snapshot still produces
-  meaningful windows (and the 7-day staleness check is relative to it). The
-  anchor date is shown in the header.
-- **`date`, not `creationdate`, for windows.** `creationdate`/`lastmodified` are
-  unindexed on `tickets`; range-scanning them can time out (HTTP 503). The
-  indexed `date` column is used for opened-in-window queries.
-- **Roles aren't distinguished.** Every active user is included; a salesperson
-  with no tickets shows as *Idle*. Use the team filter / search to focus on a
-  delivery team.
-
-> `data.js` / `data.json` are generated and contain real names from your
-> instance — they are git-ignored. Commit only the source.