Getting Started

The ZeyOS JavaScript client provides a generated, dependency-light interface to the ZeyOS REST API. It works in both browser environments and Node.js 18+, with built-in support for OAuth 2.0, session-based authentication, and automatic token refresh.

Use the JavaScript client when:

• the CLI resource registry is not enough
• you are building a browser UI or a server-side integration
• you need request-level control through client.request()
• you want access to the full generated API surface instead of the CLI's curated subset

Installation

ESM only

@zeyos/client is an ES module (ESM) package. Use import (or dynamic import()) to load it. CommonJS require() is not supported.

The client is distributed as an ES module source package. If you are working inside this repository, import it directly from the source tree:

JavaScript

import { createZeyosClient } from './src/index.js';

If you are consuming it from another project, install the package and import it by name:

Bash

npm install @zeyos/client

JavaScript

import { createZeyosClient } from '@zeyos/client';

The client has zero runtime dependencies and relies only on the standard fetch API available in modern browsers and Node.js 18+.

Creating a Client

The createZeyosClient factory function returns a frozen client object with generated API methods, OAuth 2.0 helpers, and low-level request capabilities.

JavaScript

import { createZeyosClient } from '@zeyos/client';

const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
  auth: {
    mode: 'session',
    session: { enabled: true, credentials: 'include' },
  },
});

const tickets = await client.api.listTickets({ limit: 10 });

The returned client object exposes:

• client.api -- Generated methods for all standard REST operations (e.g. listTickets, createAccount, getTask)
• client.oauth2 -- OAuth 2.0 token operations and authorization URL helpers
• client.legacyAuth -- Legacy session authentication operations (login, logout, verify, getUserInfo)
• client.request() -- Low-level escape hatch for custom or advanced requests
• client.schema -- Runtime introspection and input validation (describe, fields, resources, operations, validate); see Making Requests
• client.auth -- Token management (getTokenSet, setTokenSet, clearTokenSet)
• client.metadata -- Read-only info about the generated client (generatedAt timestamp, services array)

Alongside the createZeyosClient factory, the package exports a few named helpers and error types you can import directly:

JavaScript

import {
  createZeyosClient,
  MemoryTokenStore,        // in-memory token store (or implement get()/set() yourself)
  ZeyosApiError,           // thrown on non-2xx responses
  ZeyosValidationError,    // thrown by pre-flight validation (validate: true)
  normalizeListResult,     // normalise a list response to { data, count? }
  normalizeCountResult,    // normalise a count response to a number
  normalizeTokenSet,       // normalise a raw token object to a TokenSet
  tokenResponseToTokenSet, // map an OAuth token response to a TokenSet
} from '@zeyos/client';

Platform Configuration

The platform option tells the client where your ZeyOS instance lives. There are three ways to specify it:

URL String

Pass the full URL to your ZeyOS instance. The client extracts the origin and instance name automatically.

JavaScript

const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
});

Preset

Use a named preset for the ZeyOS cloud platform, combined with an instance name:

JavaScript

const client = createZeyosClient({
  platform: 'live',
  instance: 'demo',
});

The live preset resolves to https://cloud.zeyos.com.

Object

For full control, pass an object with origin and instance:

JavaScript

const client = createZeyosClient({
  platform: {
    origin: 'https://cloud.zeyos.com',
    instance: 'demo',
  },
});

Features

• Zero dependencies -- no external packages; only the standard fetch API is required
• Browser + Node.js 18+ -- works in any environment with global fetch
• Auto token refresh -- transparently refreshes expired access tokens before requests or after bearer 401 responses
• Generated API methods -- the broader generated API surface is available as client.api.<operationId>()
• Session + OAuth support -- choose between cookie-based sessions, bearer tokens, or automatic fallback
• Low-level escape hatch -- client.request() for custom endpoints and advanced use cases

Configuration Reference

Option	Type	Description
platform	string | { origin?: string, instance?: string, preset?: string, url?: string }	ZeyOS instance URL, preset name (e.g. 'live'), or object with origin/instance (and optionally preset or url)
platform.origin	string	Base origin URL (e.g. 'https://cloud.zeyos.com')
platform.instance	string	Instance name (e.g. 'demo')
platform.preset	string	Named preset (e.g. 'live') used when origin is omitted
platform.url	string	Full instance URL as an alternative to origin+instance
instance	string	Top-level instance name shortcut (used with preset-style platform)
auth.mode	string	Authentication mode: 'auto' (default), 'oauth', 'session', or 'none'
auth.oauth.clientId	string	OAuth 2.0 client ID for token operations
auth.oauth.clientSecret	string	OAuth 2.0 client secret for token operations
auth.oauth.tokenStore	TokenStore	Token storage backend (must implement get() and set())
auth.oauth.autoRefresh	boolean	Automatically refresh access tokens before requests or after bearer 401 responses (default: true)
auth.session.enabled	boolean	Enable session-based authentication (default: true)
auth.session.credentials	string	Fetch credentials mode: 'include', 'same-origin', or 'omit'
auth.session.cookie	string | () => string | Promise<string>	Explicit session cookie value or async function returning one (Node.js)
headers	HeadersInit	Default headers applied to every request
fetch	typeof fetch	Custom fetch implementation (defaults to globalThis.fetch)
retry	{ maxRetries?: number, retryOn?: number[], baseDelayMs?: number, maxDelayMs?: number } | false	Transient-failure retry policy. Default retries 429/503 twice with exponential backoff, honoring Retry-After. Pass false to disable. See Making Requests
validate	boolean	When true, validate each request against the schema before sending and throw ZeyosValidationError on problems (default: false). See Making Requests

Next Steps

• Application Developers -- choose the browser or server-side integration path
• Authentication -- learn about session mode, OAuth 2.0 flows, and token management
• Making Requests -- explore CRUD operations, filtering, sorting, pagination, and error handling
• Practical Guide -- real-world patterns and gotchas discovered during implementation
• Sample Application -- run the included Kanban board demo to see the client in action