@zeyos/client 0.1.0

package/docs/01-api-reference/02-authentication.md

@@ -0,0 +1,288 @@
+---
+sidebar_label: Authentication
+---
+
+# Authentication
+
+The ZeyOS API supports multiple authentication methods to accommodate different use cases -- from server-side integrations to browser-based applications. This guide covers OAuth2 token-based authentication, session cookie authentication, and the helpers provided by the `@zeyos/client` library.
+
+## Authentication Overview
+
+ZeyOS exposes an OAuth2-compatible authorization server at:
+
+```
+https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/
+```
+
+This endpoint supports the standard OAuth 2.0 Authorization Code flow, token refresh, token revocation, and token introspection. For browser applications where the user is already logged into ZeyOS, session cookie authentication is also available.
+
+## OAuth 2.0 Authorization Code Flow
+
+The Authorization Code flow is the recommended approach for server-side applications and other trusted integrations that need to act on behalf of a user.
+
+### Step 1: Build the Authorization URL
+
+Redirect the user to the ZeyOS authorization endpoint to request access. The JavaScript example below assumes a trusted environment that can safely hold OAuth client credentials:
+
+```js
+import { createZeyosClient } from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo',
+  auth: {
+    oauth: {
+      clientId: 'YOUR_CLIENT_ID',
+      clientSecret: 'YOUR_CLIENT_SECRET',
+    },
+  },
+});
+
+const authUrl = client.oauth2.buildAuthorizationUrl({
+  redirectUri: 'https://yourapp.example.com/callback',
+  state: 'random-csrf-token',
+});
+
+// Redirect the user to authUrl
+```
+
+The authorization URL follows this format:
+
+```
+https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/authorize
+  ?client_id=YOUR_CLIENT_ID
+  &redirect_uri=https://yourapp.example.com/callback
+  &response_type=code
+  &state=random-csrf-token
+```
+
+### Step 2: User Authorizes
+
+The user logs in (if not already authenticated) and approves access to your application. ZeyOS redirects the user back to your `redirect_uri` with an authorization code:
+
+```
+https://yourapp.example.com/callback?code=AUTHORIZATION_CODE&state=random-csrf-token
+```
+
+### Step 3: Exchange the Code for Tokens
+
+Exchange the authorization code for an access token and refresh token:
+
+**Using the JavaScript client:**
+
+```js
+const callback = client.oauth2.parseAuthorizationCallback(callbackUrl);
+
+if (callback.isError) {
+  console.error('Authorization failed:', callback.errorDescription);
+} else {
+  const tokenSet = await client.oauth2.exchangeAuthorizationCode({
+    code: callback.code,
+    redirectUri: 'https://yourapp.example.com/callback',
+  });
+
+  console.log('Access token:', tokenSet.accessToken);
+  console.log('Refresh token:', tokenSet.refreshToken);
+}
+```
+
+**Using curl:**
+
+```bash
+curl -X POST "https://cloud.zeyos.com/demo/oauth2/v1/token" \
+  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=authorization_code" \
+  -d "code=AUTHORIZATION_CODE" \
+  -d "redirect_uri=https://yourapp.example.com/callback"
+```
+
+**Response:**
+
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIs...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
+}
+```
+
+### Step 4: Use the Bearer Token
+
+Include the access token in the `Authorization` header for all API requests:
+
+```bash
+curl -X POST "https://cloud.zeyos.com/demo/api/v1/tickets" \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
+  -H "Content-Type: application/json" \
+  -d '{"limit": 10}'
+```
+
+With the JavaScript client, tokens are managed automatically once stored:
+
+```js
+const tickets = await client.api.listTickets({ limit: 10 });
+```
+
+## Token Refresh
+
+Access tokens expire after a limited time (indicated by `expires_in` in the token response). Use the refresh token to obtain a new access token without requiring user interaction.
+
+**Using the JavaScript client:**
+
+```js
+const newTokenSet = await client.oauth2.refreshToken();
+```
+
+:::tip
+When you configure `autoRefresh: true` in the client's OAuth settings, expired access tokens are refreshed automatically before each request. This requires `clientId` and `clientSecret`, so treat it as a trusted-environment pattern.
+:::
+
+**Using curl:**
+
+```bash
+curl -X POST "https://cloud.zeyos.com/demo/oauth2/v1/token" \
+  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=refresh_token" \
+  -d "refresh_token=dGhpcyBpcyBhIHJlZnJlc2g..."
+```
+
+## Token Revocation
+
+Revoke a token when the user logs out or your application no longer needs access:
+
+**Using the JavaScript client:**
+
+```js
+await client.oauth2.revokeToken({
+  token: tokenSet.accessToken,
+});
+```
+
+**Using curl:**
+
+```bash
+curl -X POST "https://cloud.zeyos.com/demo/oauth2/v1/revoke" \
+  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "token=eyJhbGciOiJSUzI1NiIs..."
+```
+
+## Session Authentication
+
+For browser-based applications where the user is already logged into ZeyOS, session cookie authentication provides a seamless experience without requiring a separate OAuth flow.
+
+### How It Works
+
+When a user is logged into ZeyOS in their browser, ZeyOS sets a session cookie (`ZEYOSID`). By including `credentials: 'include'` in fetch requests, the browser automatically sends this cookie, authenticating the request.
+
+### Client Configuration
+
+```js
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo',
+  auth: {
+    mode: 'session',
+    session: {
+      enabled: true,
+      credentials: 'include',
+    },
+  },
+});
+```
+
+### Checking Session Status
+
+You can verify whether the user has an active session by calling the `userinfo` endpoint:
+
+```js
+const endpoint = 'https://cloud.zeyos.com/demo/oauth2/v1/userinfo';
+const response = await fetch(endpoint, {
+  method: 'GET',
+  credentials: 'include',
+  headers: { 'Accept': 'application/json' },
+});
+
+if (response.ok) {
+  const userInfo = await response.json();
+  console.log('Logged in as:', userInfo.sub);
+}
+```
+
+:::info
+Session authentication only works in browser environments where the user is on the same domain (or an allowed origin) as the ZeyOS instance. It will not work in Node.js or server-side contexts.
+:::
+
+:::warning
+Do not embed `clientSecret` in shipped browser-only code. For browser apps, prefer session-cookie authentication or perform the OAuth code exchange and refresh on a backend that stores the client credentials safely.
+:::
+
+## Security Schemes
+
+The ZeyOS API supports three authentication schemes. Each API operation declares which schemes it accepts:
+
+| Scheme | Type | Transport | Use Case |
+|--------|------|-----------|----------|
+| **Bearer** (OAuth2) | Token | `Authorization: Bearer {token}` | Server-side apps, SPAs, CLI tools |
+| **Session** (Cookie) | Cookie | `Cookie: ZEYOSID={session_id}` | Browser apps where user is logged into ZeyOS |
+| **Basic** (Client Credentials) | Header | `Authorization: Basic {base64}` | OAuth2 token endpoint requests |
+
+Most API resource operations accept both **Bearer** and **Session** authentication. The OAuth2 token endpoints (`/token`, `/revoke`, `/introspect`) use **Basic** authentication with your client credentials.
+
+The `@zeyos/client` library handles scheme selection automatically based on your configuration:
+
+- `mode: 'auto'` (default) -- Tries bearer first if tokens are available, falls back to session.
+- `mode: 'oauth'` -- Uses bearer tokens exclusively.
+- `mode: 'session'` -- Uses session cookies exclusively.
+- `mode: 'none'` -- No authentication (for public endpoints).
+
+:::warning
+Never expose your `client_secret` in client-side JavaScript. For browser-based SPAs, use the session authentication mode or implement a server-side proxy for the token exchange. Keep OAuth client credentials on your backend server where they cannot be inspected by end users.
+:::
+
+## Token Management
+
+The client library provides built-in token storage and management:
+
+```js
+// Read the current token set
+const tokenSet = await client.auth.getTokenSet();
+
+// Manually set tokens (e.g., after loading from a database)
+await client.auth.setTokenSet({
+  accessToken: 'new-access-token',
+  refreshToken: 'new-refresh-token',
+  expiresAt: Math.floor(Date.now() / 1000) + 3600,
+});
+
+// Clear all stored tokens (logout)
+await client.auth.clearTokenSet();
+```
+
+For custom persistence (e.g., storing tokens in a database or encrypted file), implement the `TokenStore` interface:
+
+```js
+const customStore = {
+  async get() {
+    // Return the stored token set or null
+    return loadFromDatabase();
+  },
+  async set(tokenSet) {
+    // Persist the token set (or null to clear)
+    await saveToDatabase(tokenSet);
+  },
+};
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo',
+  auth: {
+    oauth: {
+      tokenStore: customStore,
+      clientId: 'YOUR_CLIENT_ID',
+      clientSecret: 'YOUR_CLIENT_SECRET',
+      autoRefresh: true,
+    },
+  },
+});
+```

package/docs/01-api-reference/03-resources.md

@@ -0,0 +1,270 @@
+---
+sidebar_label: Resources
+---
+
+# Resources
+
+The ZeyOS REST API exposes a comprehensive set of resources covering CRM, project management, ticketing, commerce, communication, and more. Each resource maps to a RESTful endpoint under the base URL and supports a consistent set of operations.
+
+:::info API Surface vs. CLI Surface
+This page documents the **full API surface** exposed by ZeyOS. The CLI intentionally supports a curated subset of common resources. For the CLI boundary and escalation path, see [CLI Coverage and Escalation](../04-agent-workflows/03-cli-coverage-and-escalation.md).
+:::
+
+## Available Resources
+
+The table below lists all available API resources and their supported operations.
+
+| Resource | Endpoint | List | Get | Create | Update | Delete |
+|----------|----------|:----:|:---:|:------:|:------:|:------:|
+| Accounts | `/accounts` | Yes | Yes | Yes | Yes | Yes |
+| ActionSteps | `/actionsteps` | Yes | Yes | Yes | Yes | Yes |
+| Addresses | `/addresses` | Yes | Yes | Yes | Yes | Yes |
+| Applications | `/applications` | Yes | Yes | -- | -- | -- |
+| ApplicationAssets | `/applicationassets` | Yes | Yes | -- | -- | -- |
+| Appointments | `/appointments` | Yes | Yes | Yes | Yes | Yes |
+| Associations | `/associations` | Yes | Yes | Yes | Yes | Yes |
+| BinFiles | `/binfiles` | Yes | -- | -- | -- | -- |
+| Campaigns | `/campaigns` | Yes | Yes | Yes | Yes | Yes |
+| Categories | `/categories` | Yes | Yes | Yes | Yes | Yes |
+| Channels | `/channels` | Yes | Yes | Yes | Yes | Yes |
+| Comments | `/comments` | Yes | Yes | Yes | Yes | Yes |
+| Components | `/components` | Yes | Yes | Yes | Yes | Yes |
+| Contacts | `/contacts` | Yes | Yes | Yes | Yes | Yes |
+| ContactsToContacts | `/contactstocontacts` | Yes | Yes | Yes | Yes | Yes |
+| Contracts | `/contracts` | Yes | Yes | Yes | Yes | Yes |
+| Coupons | `/coupons` | Yes | Yes | Yes | Yes | Yes |
+| CouponCodes | `/couponcodes` | Yes | Yes | Yes | Yes | Yes |
+| CustomFields | `/customfields` | Yes | Yes | -- | -- | -- |
+| DAVServers | `/davservers` | Yes | Yes | Yes | Yes | Yes |
+| Devices | `/devices` | Yes | Yes | Yes | Yes | Yes |
+| Documents | `/documents` | Yes | Yes | Yes | Yes | Yes |
+| DunningNotices | `/dunningnotices` | Yes | Yes | Yes | Yes | Yes |
+| DunningToTransactions | `/dunningtotransactions` | Yes | Yes | Yes | Yes | Yes |
+| EntitiesToChannels | `/entitiestochannels` | Yes | Yes | Yes | Yes | Yes |
+| Events | `/events` | Yes | Yes | Yes | Yes | Yes |
+| FeedServers | `/feedservers` | Yes | Yes | Yes | Yes | Yes |
+| Files | `/files` | Yes | Yes | Yes | Yes | Yes |
+| Follows | `/follows` | Yes | Yes | Yes | Yes | Yes |
+| Forks | `/forks` | Yes | Yes | -- | -- | -- |
+| Groups | `/groups` | Yes | Yes | -- | -- | -- |
+| GroupsToUsers | `/groupstousers` | Yes | Yes | -- | -- | -- |
+| Invitations | `/invitations` | Yes | Yes | Yes | Yes | Yes |
+| Items | `/items` | Yes | Yes | Yes | Yes | Yes |
+| Ledgers | `/ledgers` | Yes | Yes | Yes | Yes | Yes |
+| Likes | `/likes` | Yes | Yes | Yes | Yes | Yes |
+| Links | `/links` | Yes | Yes | Yes | Yes | Yes |
+| MailingLists | `/mailinglists` | Yes | Yes | Yes | Yes | Yes |
+| MailingRecipients | `/mailingrecipients` | Yes | Yes | Yes | Yes | Yes |
+| MailServers | `/mailservers` | Yes | Yes | Yes | Yes | Yes |
+| Messages | `/messages` | Yes | Yes | Yes | Yes | Yes |
+| MessageReads | `/messagereads` | Yes | Yes | Yes | Yes | Yes |
+| Notes | `/notes` | Yes | Yes | Yes | Yes | Yes |
+| Objects | `/objects` | Yes | Yes | Yes | Yes | Yes |
+| Opportunities | `/opportunities` | Yes | Yes | Yes | Yes | Yes |
+| Participants | `/participants` | Yes | Yes | Yes | Yes | Yes |
+| Payments | `/payments` | Yes | Yes | Yes | Yes | Yes |
+| Permissions | `/permissions` | Yes | Yes | -- | -- | -- |
+| PriceLists | `/pricelists` | Yes | Yes | Yes | Yes | Yes |
+| PriceListsToAccounts | `/priceliststoaccounts` | Yes | Yes | Yes | Yes | Yes |
+| Prices | `/prices` | Yes | Yes | Yes | Yes | Yes |
+| Projects | `/projects` | Yes | Yes | Yes | Yes | Yes |
+| Records | `/records` | Yes | Yes | Yes | Yes | Yes |
+| RelatedItems | `/relateditems` | Yes | Yes | Yes | Yes | Yes |
+| Resources | `/resources` | Yes | Yes | -- | -- | -- |
+| Services | `/services` | Yes | Yes | -- | -- | -- |
+| StockTransactions | `/stocktransactions` | Yes | Yes | Yes | Yes | Yes |
+| Storages | `/storages` | Yes | Yes | Yes | Yes | Yes |
+| Suppliers | `/suppliers` | Yes | Yes | Yes | Yes | Yes |
+| Tasks | `/tasks` | Yes | Yes | Yes | Yes | Yes |
+| Tickets | `/tickets` | Yes | Yes | Yes | Yes | Yes |
+| Transactions | `/transactions` | Yes | Yes | Yes | Yes | Yes |
+| Users | `/users` | Yes | Yes | -- | -- | -- |
+| Weblets | `/weblets` | Yes | Yes | -- | -- | -- |
+
+## Common Resources
+
+The following resources are the most frequently used when building integrations with ZeyOS.
+
+### Tickets
+
+Support and service tickets with status tracking, priority levels, due dates, and assignment to users. Tickets are the central work item in ZeyOS and can be linked to accounts, projects, contacts, and tasks.
+
+```js
+// List open tickets sorted by priority
+const tickets = await client.api.listTickets({
+  filters: { visibility: 0, status: 4 },
+  sort: ['-priority', '+duedate'],
+  limit: 50,
+});
+
+// Get a single ticket with extended data
+const ticket = await client.api.getTicket({ ID: 12345, extdata: 1, tags: 1 });
+
+// Create a new ticket
+const newTicket = await client.api.createTicket({
+  name: 'Server maintenance required',
+  priority: 3,
+  status: 0,
+});
+
+// Update a ticket — flat spread form or explicit body key both work
+await client.api.updateTicket({ ID: 12345, status: 4, priority: 4 });
+// Equivalent using explicit body key:
+// await client.api.updateTicket({ ID: 12345, body: { status: 4, priority: 4 } });
+```
+
+### Accounts
+
+Customer and company records that serve as the primary organizational entity in the CRM. Accounts can have linked contacts, tickets, documents, and transactions.
+
+```js
+const accounts = await client.api.listAccounts({
+  fields: ['ID', 'lastname', 'firstname'],
+  filters: { visibility: 0 },
+  sort: ['+lastname'],
+  limit: 100,
+});
+```
+
+### Contacts
+
+Individual people linked to accounts. Contacts store personal details such as name, email, phone, and address information.
+
+```js
+const contacts = await client.api.listContacts({
+  fields: {
+    Id: 'ID',
+    Name: 'lastname',
+    Email: 'email',
+    Company: 'account.lastname',
+  },
+  filters: { visibility: 0 },
+  sort: ['+lastname'],
+});
+```
+
+### Tasks
+
+Actionable work items that can be linked to tickets, projects, or other entities. Tasks track completion status and can be assigned to users.
+
+```js
+const tasks = await client.api.listTasks({
+  filters: { ticket: 12345, visibility: 0 },
+  sort: ['+name'],
+  limit: 200,
+});
+```
+
+### Projects
+
+Organizational groupings for tickets, tasks, and other work items. Projects provide a way to plan and track larger initiatives.
+
+```js
+const projects = await client.api.listProjects({
+  fields: ['ID', 'name'],
+  filters: { visibility: 0 },
+  sort: ['+name'],
+});
+```
+
+### Items
+
+Products and services with pricing information. Items are referenced in documents (invoices, quotes) and can be linked to price lists, categories, and suppliers.
+
+```js
+const items = await client.api.listItems({
+  fields: ['ID', 'name', 'price', 'unit'],
+  sort: ['+name'],
+  limit: 100,
+});
+```
+
+### Documents
+
+Business documents such as invoices, quotes, orders, and delivery notes. Documents are linked to accounts and contain line items referencing products/services.
+
+```js
+const invoices = await client.api.listDocuments({
+  filters: { doctype: 'invoice', visibility: 0 },
+  sort: ['-date'],
+  limit: 25,
+});
+```
+
+## Resource Naming
+
+The API follows consistent naming conventions for endpoints and operations:
+
+### Endpoint Paths
+
+Resource endpoints use **plural, lowercase** paths:
+
+```
+/accounts
+/tickets
+/contacts
+/documents
+```
+
+Individual records are accessed by appending `/{ID}`:
+
+```
+/accounts/{ID}
+/tickets/{ID}
+```
+
+### Operation IDs
+
+The JavaScript client uses camelCase operation IDs that follow a verb-noun pattern:
+
+| Operation | Pattern | Example |
+|-----------|---------|---------|
+| List | `list{Resources}` | `listTickets`, `listAccounts` |
+| Get | `get{Resource}` | `getTicket`, `getAccount` |
+| Create | `create{Resource}` | `createTicket`, `createAccount` |
+| Update | `update{Resource}` | `updateTicket`, `updateAccount` |
+| Delete | `delete{Resource}` | `deleteTicket`, `deleteAccount` |
+| Exists | `exists{Resource}` | `existsTicket`, `existsAccount` |
+
+All operations are available as methods on the `client.api` object:
+
+```js
+// List operations accept query parameters (fields, filter, sort, etc.)
+const results = await client.api.listTickets({ limit: 10 });
+
+// Get operations require an ID path parameter
+const ticket = await client.api.getTicket({ ID: 123 });
+
+// Create operations accept a request body
+const created = await client.api.createTicket({ name: 'New ticket' });
+
+// Update operations require an ID and changed fields (flat spread or explicit body key)
+await client.api.updateTicket({ ID: 123, status: 4 });
+
+// Delete operations require an ID
+await client.api.deleteTicket({ ID: 123 });
+
+// Exists operations return a boolean-like HEAD response
+await client.api.existsTicket({ ID: 123 });
+```
+
+:::info
+The client library is auto-generated from the OpenAPI specification files located in the `/openapi/` directory of this project. The spec files (`api.json`, `oauth2.json`, `auth.json`) define every available resource, operation, parameter, and response schema. Run `npm run generate` to regenerate the client after modifying the spec files.
+:::
+
+## HTTP Methods
+
+The API uses the following HTTP methods, which may differ from typical REST conventions:
+
+| Operation | HTTP Method | Description |
+|-----------|-------------|-------------|
+| List | `POST` | Retrieve a filtered list of records (body contains query parameters) |
+| Get | `GET` | Retrieve a single record by ID |
+| Create | `PUT` | Create a new record |
+| Update | `PATCH` | Partially update an existing record |
+| Delete | `DELETE` | Delete a record by ID |
+| Exists | `HEAD` | Check if a record exists (returns no body) |
+
+:::tip
+Note that **list** operations use `POST` rather than `GET`. This is because the query language (filters, field selection, sorting) can produce request payloads that exceed URL length limits. Using `POST` allows complex queries to be sent reliably in the request body.
+:::