@zeyos/client 0.1.1 → 0.3.0

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.
@@ -113,6 +144,7 @@ zeyos list <resource> [options]
 |--------|-------------|
 | `--fields <fields>` | Field selection — comma-separated, JSON object, or JSON array (see below) |
 | `--filter <json>` | Filter criteria — JSON object |
+| `--filter-file <path>` | Read filter criteria from a JSON file |
 | `--sort <fields>` | Sort fields, comma-separated (prefix `+` asc, `-` desc) |
 | `--limit <n>` | Maximum records to return (default: `50`) |
 | `--offset <n>` | Skip the first n records |
@@ -140,6 +172,9 @@ zeyos list tickets
 # Custom filters
 zeyos list tickets --filter '{"status":1,"priority":3}'
 
+# Custom filters from a file
+zeyos list tickets --filter-file ./filters/open-tickets.json
+
 # Specify fields with aliases
 zeyos list accounts --fields '{"Name":"lastname","City":"contact.city"}'
 
@@ -179,6 +214,7 @@ zeyos count <resource> [options]
 | Option | Description |
 |--------|-------------|
 | `--filter <json>` | Filter criteria — JSON object |
+| `--filter-file <path>` | Read filter criteria from a JSON file |
 | `--json` | Output as `{"count": N}` |
 | `--yaml` | YAML output |
 
@@ -193,6 +229,9 @@ zeyos count tickets
 zeyos count tickets --filter '{"status":1}'
 # → 12
 
+# Filtered count using a JSON file
+zeyos count tickets --filter-file ./filters/open-tickets.json
+
 # JSON output for scripting
 zeyos count accounts --json
 # → {"count": 156}
@@ -261,6 +300,7 @@ zeyos create <resource> [--data <json>] [--field value ...]
 | Option | Description |
 |--------|-------------|
 | `--data <json>` | Complete record as a JSON string |
+| `--data-file <path>` | Read the complete record from a JSON file |
 | `--<field> <value>` | Set individual field (any unknown flag becomes a field) |
 
 **Examples:**
@@ -269,6 +309,9 @@ zeyos create <resource> [--data <json>] [--field value ...]
 # Using --data JSON
 zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3}'
 
+# Using a JSON file
+zeyos create ticket --data-file ./ticket.json
+
 # Using individual field flags
 zeyos create ticket --name "Fix login bug" --status 0 --priority 3
 
@@ -301,6 +344,9 @@ zeyos update <resource> <id> [--data <json>] [--field value ...]
 # Using --data JSON
 zeyos update ticket 42 --data '{"status":4}'
 
+# Using a JSON file
+zeyos update ticket 42 --data-file ./ticket-update.json
+
 # Using field flags
 zeyos update ticket 42 --status 4 --priority 2
 
@@ -348,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.
 
 ---
 
@@ -368,6 +417,19 @@ Foreign keys are shown as `→ <table>`, and enum fields list their valid values
 
 ---
 
+## doctor
+
+Check local CLI readiness for coding agents. This runs offline and never prints tokens or client secrets.
+
+```bash
+zeyos doctor agent
+zeyos doctor agent --json
+```
+
+The report includes the CLI version, configured base URL and instance, whether auth values are present through environment/local/global config, and whether the curated resource registry can be loaded.
+
+---
+
 ## skills
 
 Discover and install the bundled ZeyOS agent skill packs into any coding agent, so the agent (Claude Code, Codex, opencode, Factory Droid, pi, …) operates against ZeyOS with the right conventions out of the box.

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.1.1",
+  "version": "0.3.0",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,9 @@
     "scripts/generate-client.mjs",
     "openapi",
     "docs",
-    "samples",
+    "samples/crm",
+    "samples/dashboard",
+    "samples/kanban",
     "agents",
     "README.md",
     "CHANGELOG.md",
@@ -44,6 +46,7 @@
     "generate": "node scripts/generate-client.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-protocol": "node test/agent-protocol/harness/run.mjs",
+    "test:agent-loop": "node test/agent-protocol/harness/loop.mjs"
   }
 }

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,7 +898,50 @@ 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
+    // work. Powers `zeyos … --query` and is handy for debugging/testing.
+    if (requestOptions.dryRun || prepared.dryRun) {
+      const baseUrl = resolveBaseUrl({
+        services: SERVICES,
+        serviceKey,
+        config,
+        explicitBaseUrl: prepared.baseUrl ?? requestOptions.baseUrl
+      });
+      const url = buildUrl(baseUrl, operation.path, prepared.pathParams, prepared.query);
+      const bodyType = chooseBodyType(serviceKey, operation, prepared, requestOptions?.bodyType);
+      return {
+        dryRun: true,
+        service: serviceKey,
+        operationId: operation.operationId,
+        method: operation.method,
+        url,
+        path: operation.path,
+        pathParams: prepared.pathParams,
+        query: prepared.query,
+        headers: prepared.headers,
+        body: prepared.body,
+        bodyType
+      };
+    }
+
     const requestAuth = normalizeRequestAuth(prepared.auth ?? requestOptions.auth);
     const mode = normalizeAuthMode(requestAuth.mode, defaultMode);
     const schemes = securitySchemesFromOperation(operation);
@@ -799,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;
         }
@@ -838,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({
@@ -990,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;
@@ -1192,6 +1398,8 @@ export function createZeyosClient(rawConfig = {}) {
     oauth2,
     legacyAuth,
     request,
+    paginate,
+    collect,
     schema: schemaApi,
     auth: {
       getTokenSet,