@zeyos/client 0.1.0

package/src/runtime/error.js

@@ -0,0 +1,29 @@
+export class ZeyosApiError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ZeyosApiError';
+
+    this.status = details.status ?? 0;
+    this.statusText = details.statusText ?? '';
+    this.headers = details.headers ?? {};
+    this.body = details.body ?? null;
+    this.method = details.method ?? '';
+    this.url = details.url ?? '';
+    this.operationId = details.operationId ?? '';
+    this.service = details.service ?? '';
+    this.cause = details.cause;
+  }
+}
+
+/**
+ * Thrown by pre-flight validation (when `validate: true` is enabled) before a
+ * request is sent. Carries structured, self-correcting hints for agents.
+ */
+export class ZeyosValidationError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ZeyosValidationError';
+    this.operationId = details.operationId ?? '';
+    this.errors = Array.isArray(details.errors) ? details.errors : [];
+  }
+}

package/src/runtime/http.js

@@ -0,0 +1,174 @@
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+function encodePrimitive(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return String(value);
+}
+
+function appendQueryValue(search, key, value) {
+  if (value == null) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendQueryValue(search, key, item);
+    }
+    return;
+  }
+
+  if (isPlainObject(value)) {
+    search.append(key, JSON.stringify(value));
+    return;
+  }
+
+  search.append(key, encodePrimitive(value));
+}
+
+function buildQueryString(query = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    appendQueryValue(search, key, value);
+  }
+  return search.toString();
+}
+
+function applyPathParams(pathTemplate, pathParams = {}) {
+  return pathTemplate.replace(/\{([^}]+)\}/g, (_, token) => {
+    if (!Object.prototype.hasOwnProperty.call(pathParams, token)) {
+      throw new Error(`Missing path parameter: ${token}`);
+    }
+    const rawValue = pathParams[token];
+    if (rawValue == null) {
+      throw new Error(`Path parameter cannot be null: ${token}`);
+    }
+    return encodeURIComponent(String(rawValue));
+  });
+}
+
+export function buildUrl(baseUrl, pathTemplate, pathParams = {}, query = {}) {
+  const normalizedBase = String(baseUrl || '').replace(/\/+$/, '');
+  const resolvedPath = applyPathParams(pathTemplate, pathParams);
+  const normalizedPath = resolvedPath.startsWith('/') ? resolvedPath : `/${resolvedPath}`;
+
+  const rawUrl = `${normalizedBase}${normalizedPath}`;
+  const queryString = buildQueryString(query);
+
+  return queryString ? `${rawUrl}?${queryString}` : rawUrl;
+}
+
+function valueToFormValues(value) {
+  if (value == null) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => valueToFormValues(item));
+  }
+
+  if (isPlainObject(value)) {
+    return [JSON.stringify(value)];
+  }
+
+  return [encodePrimitive(value)];
+}
+
+function toFormUrlEncoded(value) {
+  const search = new URLSearchParams();
+  if (!value || typeof value !== 'object') {
+    return search.toString();
+  }
+
+  for (const [key, rawValue] of Object.entries(value)) {
+    for (const part of valueToFormValues(rawValue)) {
+      search.append(key, part);
+    }
+  }
+
+  return search.toString();
+}
+
+function headersToObject(headers) {
+  const result = {};
+  for (const [key, value] of headers.entries()) {
+    result[key] = value;
+  }
+  return result;
+}
+
+async function parseResponseBody(response, method) {
+  if (method === 'HEAD' || response.status === 204 || response.status === 205 || response.status === 304) {
+    return null;
+  }
+
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+
+  const contentType = response.headers.get('content-type') || '';
+  const isJson = /(^|\b|;)application\/([a-z0-9.+-]*\+)?json\b/i.test(contentType);
+
+  if (!isJson) {
+    return text;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export async function httpRequest({
+  fetchImpl,
+  url,
+  method,
+  headers = {},
+  body,
+  bodyType,
+  signal,
+  credentials
+}) {
+  const requestHeaders = new Headers(headers);
+  let payload;
+
+  if (body != null) {
+    if (bodyType === 'form') {
+      if (!requestHeaders.has('content-type')) {
+        requestHeaders.set('content-type', 'application/x-www-form-urlencoded');
+      }
+      payload = toFormUrlEncoded(body);
+    } else if (bodyType === 'json') {
+      if (!requestHeaders.has('content-type')) {
+        requestHeaders.set('content-type', 'application/json');
+      }
+      payload = JSON.stringify(body);
+    } else {
+      payload = body;
+    }
+  }
+
+  const response = await fetchImpl(url, {
+    method,
+    headers: requestHeaders,
+    body: payload,
+    signal,
+    credentials
+  });
+
+  const data = await parseResponseBody(response, method);
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    headers: headersToObject(response.headers),
+    data,
+    response
+  };
+}

package/src/runtime/request-shape.js

@@ -0,0 +1,35 @@
+/**
+ * Request-level keys accepted by generated methods and `client.request()`.
+ * These are control fields consumed by the client, not resource payload fields.
+ */
+export const REQUEST_CONTROL_KEYS = Object.freeze([
+  'path',
+  'query',
+  'headers',
+  'body',
+  'data',
+  'auth',
+  'bodyType',
+  'signal',
+  'raw',
+  'baseUrl'
+]);
+
+/**
+ * Validation accepts request options as a second argument, so `validate` is only
+ * a field-validation control key, not a request payload control key.
+ */
+export const VALIDATION_CONTROL_KEYS = Object.freeze([
+  ...REQUEST_CONTROL_KEYS,
+  'validate'
+]);
+
+/**
+ * Control keys that act as containers only when object-valued. A scalar `query`
+ * can be a legitimate ZeyOS payload field for full-text search.
+ */
+export const OBJECT_CONTROL_KEYS = Object.freeze([
+  'path',
+  'query',
+  'headers'
+]);

package/src/runtime/schema.js

@@ -0,0 +1,206 @@
+import { suggestClosest } from './suggest.js';
+import { VALIDATION_CONTROL_KEYS } from './request-shape.js';
+
+// Top-level body keys on list/count queries are query directives, not resource
+// fields. Resource field names appear *inside* `filters`/`filter`/`fields`.
+const QUERY_DIRECTIVES = new Set([
+  'fields', 'filter', 'filters', 'sort', 'limit', 'offset', 'count',
+  'query', 'distinct', 'expand', 'extdata', 'tags', 'group', 'having', 'visibility'
+]);
+
+// Request-level control keys consumed by the client, never resource fields.
+const CONTROL_KEYS = new Set(VALIDATION_CONTROL_KEYS);
+
+// The ZeyOS OpenAPI spec carries NO required-field metadata — every schema's
+// `required` array is empty — yet some columns are NOT NULL with no DB default, so
+// a create that omits them fails server-side with an opaque HTTP 500 (a raw pg
+// constraint error). This curated map supplements the spec with confirmed-required
+// create fields so validate() can surface a clean, self-correcting hint instead.
+// Keyed by schema resource name; extend as other NOT-NULL-without-default columns
+// are confirmed.
+const REQUIRED_CREATE_FIELDS = {
+  accounts: ['currency']
+};
+
+function resourceFromPath(path) {
+  if (typeof path !== 'string') return null;
+  for (const segment of path.split('/')) {
+    if (segment && !segment.startsWith('{')) return segment;
+  }
+  return null;
+}
+
+// A field reference may be a dot-notation join (`contact.city`), an extended
+// field (`extdata.region`) or an alias map value. Reduce it to the base column
+// name on the primary resource so it can be checked against the schema.
+function baseFieldName(ref) {
+  if (typeof ref !== 'string') return null;
+  const head = ref.split('.')[0].trim();
+  return head || null;
+}
+
+/**
+ * Build the read-only `client.schema` surface: runtime introspection of
+ * resources, fields, enums and operations, plus best-effort input validation
+ * that produces agent-friendly, self-correcting hints.
+ */
+export function createSchema({ services, schema }) {
+  const schemaMap = schema && typeof schema === 'object' ? schema : {};
+  const resourceNames = Object.keys(schemaMap);
+
+  const opIndex = new Map();
+  const allOperationIds = [];
+  for (const [serviceKey, service] of Object.entries(services || {})) {
+    for (const operation of service.operations || []) {
+      allOperationIds.push(operation.operationId);
+      opIndex.set(operation.operationId, {
+        service: serviceKey,
+        operation,
+        resource: resourceFromPath(operation.path)
+      });
+    }
+  }
+
+  function resources() {
+    return resourceNames.slice();
+  }
+
+  function describe(resource) {
+    const entry = schemaMap[resource];
+    if (!entry) return null;
+    return { name: resource, type: entry.type, fields: entry.fields };
+  }
+
+  function fields(resource) {
+    const entry = schemaMap[resource];
+    return entry ? Object.keys(entry.fields) : [];
+  }
+
+  function operationIds() {
+    return allOperationIds.slice();
+  }
+
+  function operations(resource) {
+    if (resource == null) return allOperationIds.slice();
+    return allOperationIds.filter((id) => opIndex.get(id)?.resource === resource);
+  }
+
+  function resourceForOperation(operationId) {
+    return opIndex.get(operationId)?.resource ?? null;
+  }
+
+  function suggestOperation(name) {
+    return suggestClosest(name, allOperationIds);
+  }
+
+  function checkField(resourceFields, fieldDefs, ref, value, errors) {
+    const base = baseFieldName(ref);
+    if (!base) return;
+    // Dot-notation joins and extended/custom fields can't be validated against
+    // the base table — accept them rather than emit false positives.
+    if (base === 'extdata' || base !== ref) return;
+    if (!resourceFields.includes(base)) {
+      const suggestion = suggestClosest(base, resourceFields);
+      errors.push({
+        field: base,
+        message: `Unknown field "${base}".` + (suggestion ? ` Did you mean "${suggestion}"?` : ''),
+        ...(suggestion ? { suggestion } : {})
+      });
+      return;
+    }
+    const def = fieldDefs[base];
+    if (def && def.enum && (typeof value === 'string' || typeof value === 'number')) {
+      if (!Object.prototype.hasOwnProperty.call(def.enum, String(value))) {
+        const valid = Object.entries(def.enum).map(([k, v]) => `${k}=${v}`).join(', ');
+        errors.push({
+          field: base,
+          message: `Invalid value ${JSON.stringify(value)} for "${base}". Valid: ${valid}.`
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate an operation call without sending it. Never throws.
+   * @returns {{ valid: boolean, errors: { field?: string, message: string, suggestion?: string }[] }}
+   */
+  function validate(operationId, input) {
+    const errors = [];
+    const entry = opIndex.get(operationId);
+    if (!entry) {
+      const suggestion = suggestOperation(operationId);
+      errors.push({
+        message: `Unknown operation "${operationId}".` + (suggestion ? ` Did you mean "${suggestion}"?` : ''),
+        ...(suggestion ? { suggestion } : {})
+      });
+      return { valid: false, errors };
+    }
+
+    const data = input && typeof input === 'object' ? input : {};
+    const resourceEntry = schemaMap[entry.resource];
+    const resourceFields = resourceEntry ? Object.keys(resourceEntry.fields) : null;
+    const fieldDefs = resourceEntry ? resourceEntry.fields : {};
+    const isListLike = /^(list|count)/.test(operationId);
+
+    if (isListLike && Object.prototype.hasOwnProperty.call(data, 'filter')) {
+      errors.push({
+        field: 'filter',
+        message: 'Use "filters" (plural) rather than "filter" — it also matches GIN-indexed foreign-key fields (project, account, ticket).',
+        suggestion: 'filters'
+      });
+    }
+
+    if (!resourceFields) {
+      return { valid: errors.length === 0, errors };
+    }
+
+    if (isListLike) {
+      for (const key of ['filters', 'filter']) {
+        const filterObj = data[key];
+        if (filterObj && typeof filterObj === 'object' && !Array.isArray(filterObj)) {
+          for (const [field, value] of Object.entries(filterObj)) {
+            checkField(resourceFields, fieldDefs, field, value, errors);
+          }
+        }
+      }
+      const sel = data.fields;
+      const selValues = Array.isArray(sel) ? sel : (sel && typeof sel === 'object' ? Object.values(sel) : []);
+      for (const ref of selValues) checkField(resourceFields, fieldDefs, ref, undefined, errors);
+    } else {
+      for (const [key, value] of Object.entries(data)) {
+        if (CONTROL_KEYS.has(key) || QUERY_DIRECTIVES.has(key)) continue;
+        if (entry.operation.parameterNames?.path?.includes(key)) continue;
+        if (entry.operation.parameterNames?.query?.includes(key)) continue;
+        if (entry.operation.parameterNames?.header?.includes(key)) continue;
+        checkField(resourceFields, fieldDefs, key, value, errors);
+      }
+      // Create-only required-field check. The spec marks nothing required, so this
+      // uses the curated REQUIRED_CREATE_FIELDS supplement. Updates are partial by
+      // nature, so the check applies to `create*` operations only.
+      if (/^create/i.test(operationId)) {
+        for (const field of REQUIRED_CREATE_FIELDS[entry.resource] || []) {
+          if (!Object.prototype.hasOwnProperty.call(data, field) || data[field] == null) {
+            errors.push({
+              field,
+              message: `Missing required field "${field}" for ${entry.resource} — it is NOT NULL with no default, so the API rejects a create without it.`,
+              suggestion: field
+            });
+          }
+        }
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  return Object.freeze({
+    resources,
+    describe,
+    fields,
+    operations,
+    operationIds,
+    resourceForOperation,
+    suggestOperation,
+    validate
+  });
+}

package/src/runtime/suggest.js

@@ -0,0 +1,74 @@
+// Small, dependency-free fuzzy matcher used to turn "not found" failures into
+// self-correcting, agent-friendly errors ("did you mean ...?").
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    const ca = a.charCodeAt(i - 1);
+    for (let j = 1; j <= n; j++) {
+      const cost = ca === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    const tmp = prev;
+    prev = curr;
+    curr = tmp;
+  }
+
+  return prev[n];
+}
+
+/**
+ * Return the closest candidate to `name`, or null when nothing is close enough.
+ * Case-insensitive. Prefers an exact case-insensitive match, then a substring
+ * match, then the smallest edit distance within a length-scaled threshold.
+ *
+ * @param {string} name
+ * @param {Iterable<string>} candidates
+ * @returns {string|null}
+ */
+export function suggestClosest(name, candidates) {
+  if (typeof name !== 'string' || !name) return null;
+  const list = Array.from(candidates);
+  const lowerName = name.toLowerCase();
+
+  let exact = null;
+  let substring = null;
+  let best = null;
+  let bestDistance = Infinity;
+
+  for (const candidate of list) {
+    if (typeof candidate !== 'string' || !candidate) continue;
+    const lower = candidate.toLowerCase();
+
+    if (lower === lowerName) {
+      exact = candidate;
+      break;
+    }
+    if (!substring && (lower.includes(lowerName) || lowerName.includes(lower))) {
+      substring = candidate;
+    }
+
+    const distance = levenshtein(lowerName, lower);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+
+  if (exact) return exact;
+  if (substring) return substring;
+
+  // Accept the nearest match only when the edit distance is small relative to
+  // the name length, so unrelated names don't produce misleading suggestions.
+  const threshold = Math.max(2, Math.floor(name.length / 3));
+  return bestDistance <= threshold ? best : null;
+}

package/src/runtime/token-store.js

@@ -0,0 +1,105 @@
+/**
+ * @typedef {{
+ *   accessToken: string|null,
+ *   refreshToken: string|null,
+ *   tokenType: string,
+ *   expiresIn: number|null,
+ *   refreshTokenExpiresIn: number|null,
+ *   obtainedAt: number,
+ *   expiresAt: number|null,
+ *   refreshTokenExpiresAt: number|null
+ * }} TokenSet
+ *
+ * @typedef {{
+ *   accessToken?: string|null,
+ *   access_token?: string|null,
+ *   refreshToken?: string|null,
+ *   refresh_token?: string|null,
+ *   tokenType?: string|null,
+ *   token_type?: string|null,
+ *   expiresIn?: number|string|null,
+ *   expires_in?: number|string|null,
+ *   refreshTokenExpiresIn?: number|string|null,
+ *   refresh_token_expires_in?: number|string|null,
+ *   obtainedAt?: number|string|null,
+ *   obtained_at?: number|string|null,
+ *   expiresAt?: number|string|null,
+ *   expires_at?: number|string|null,
+ *   refreshTokenExpiresAt?: number|string|null,
+ *   refresh_token_expires_at?: number|string|null
+ * }} TokenSetInput
+ */
+
+function toNumber(value) {
+  if (value == null || value === '') {
+    return null;
+  }
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+/**
+ * @param {TokenSetInput|null|undefined} input
+ * @returns {TokenSet|null}
+ */
+export function normalizeTokenSet(input) {
+  if (!input || typeof input !== 'object') {
+    return null;
+  }
+
+  const accessToken = input.accessToken ?? input.access_token ?? null;
+  const refreshToken = input.refreshToken ?? input.refresh_token ?? null;
+
+  if (!accessToken && !refreshToken) {
+    return null;
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const obtainedAt = toNumber(input.obtainedAt ?? input.obtained_at) ?? nowSeconds;
+  const expiresIn = toNumber(input.expiresIn ?? input.expires_in);
+  const refreshTokenExpiresIn = toNumber(input.refreshTokenExpiresIn ?? input.refresh_token_expires_in);
+
+  const expiresAt =
+    toNumber(input.expiresAt ?? input.expires_at) ??
+    (expiresIn != null ? obtainedAt + expiresIn : null);
+
+  const refreshTokenExpiresAt =
+    toNumber(input.refreshTokenExpiresAt ?? input.refresh_token_expires_at) ??
+    (refreshTokenExpiresIn != null ? obtainedAt + refreshTokenExpiresIn : null);
+
+  return {
+    tokenType: input.tokenType ?? input.token_type ?? 'Bearer',
+    accessToken,
+    refreshToken,
+    expiresIn,
+    refreshTokenExpiresIn,
+    obtainedAt,
+    expiresAt,
+    refreshTokenExpiresAt
+  };
+}
+
+/**
+ * @param {TokenSetInput|null|undefined} tokenResponse
+ * @returns {TokenSet|null}
+ */
+export function tokenResponseToTokenSet(tokenResponse) {
+  return normalizeTokenSet(tokenResponse);
+}
+
+export class MemoryTokenStore {
+  /** @param {TokenSetInput|null} [initialToken] */
+  constructor(initialToken = null) {
+    this.token = normalizeTokenSet(initialToken);
+  }
+
+  /** @returns {Promise<TokenSet|null>} */
+  async get() {
+    return this.token;
+  }
+
+  /** @param {TokenSetInput|null} token */
+  async set(token) {
+    this.token = normalizeTokenSet(token);
+  }
+}