@nexusm/sdk 1.3.0

package/dist/index.mjs

@@ -0,0 +1,1444 @@
+// src/config.ts
+var DEFAULT_CACHE = {
+  max: 1e3,
+  ttl: 300
+  // 5 minutes
+};
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  initialDelay: 1e3,
+  maxDelay: 1e4,
+  backoffFactor: 2
+};
+var DEFAULT_CONFIG = {
+  baseUrl: "http://localhost:8001/v1",
+  timeout: 3e4,
+  // 30 seconds
+  cache: DEFAULT_CACHE,
+  retry: DEFAULT_RETRY
+};
+function resolveConfig(userConfig) {
+  if (!userConfig.apiKey) {
+    throw new Error(
+      'NexusConfig: "apiKey" is required and must be a non-empty string.'
+    );
+  }
+  let cache;
+  if (userConfig.cache === false) {
+    cache = false;
+  } else if (userConfig.cache) {
+    cache = { ...DEFAULT_CACHE, ...userConfig.cache };
+  } else {
+    cache = { ...DEFAULT_CACHE };
+  }
+  let retry;
+  if (userConfig.retry === false) {
+    retry = false;
+  } else if (userConfig.retry) {
+    retry = { ...DEFAULT_RETRY, ...userConfig.retry };
+  } else {
+    retry = { ...DEFAULT_RETRY };
+  }
+  const rawBaseUrl = userConfig.baseUrl ?? DEFAULT_CONFIG.baseUrl;
+  const baseUrl = rawBaseUrl.replace(/\/+$/, "");
+  return {
+    apiKey: userConfig.apiKey,
+    tenantId: userConfig.tenantId,
+    baseUrl,
+    timeout: userConfig.timeout ?? DEFAULT_CONFIG.timeout,
+    cache,
+    retry,
+    offline: userConfig.offline,
+    autoErrorReport: userConfig.autoErrorReport ?? false
+  };
+}
+
+// src/http/client.ts
+import axios from "axios";
+
+// src/errors/base.ts
+var NexusError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "NexusError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var ConfigurationError = class extends NexusError {
+  constructor(message, cause) {
+    super(message, "NEXUS_CONFIGURATION_ERROR", cause);
+    this.name = "ConfigurationError";
+  }
+};
+var NetworkError = class extends NexusError {
+  constructor(message, cause) {
+    super(message, "NEXUS_NETWORK_ERROR", cause);
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends NexusError {
+  constructor(message, cause) {
+    super(message, "NEXUS_TIMEOUT_ERROR", cause);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/errors/api.ts
+function extractMessage(data, fallback) {
+  if (data && typeof data === "object") {
+    const body = data;
+    return body.detail ?? body.message ?? fallback;
+  }
+  return fallback;
+}
+var ApiError = class _ApiError extends NexusError {
+  constructor(message, statusCode, response, code = "NEXUS_API_ERROR") {
+    super(message, code);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+  /**
+   * Create the most specific `ApiError` subclass from an Axios response.
+   *
+   * | Status | Error class            |
+   * |--------|------------------------|
+   * | 400    | `ValidationError`      |
+   * | 401    | `AuthenticationError`  |
+   * | 404    | `NotFoundError`        |
+   * | 429    | `RateLimitError`       |
+   * | other  | `ApiError`             |
+   */
+  static fromResponse(response) {
+    const { status, data, headers } = response;
+    switch (status) {
+      case 400: {
+        const msg = extractMessage(data, "Validation failed");
+        const details = data && typeof data === "object" ? data.errors : void 0;
+        return new ValidationError(msg, details, data);
+      }
+      case 401: {
+        const msg = extractMessage(data, "Authentication failed");
+        return new AuthenticationError(msg, data);
+      }
+      case 404: {
+        const msg = extractMessage(data, "Resource not found");
+        return new NotFoundError(msg, data);
+      }
+      case 429: {
+        const msg = extractMessage(data, "Rate limit exceeded");
+        const retryAfter = headers?.["retry-after"] ? Number(headers["retry-after"]) : void 0;
+        return new RateLimitError(msg, retryAfter, data);
+      }
+      default: {
+        const msg = extractMessage(
+          data,
+          `API request failed with status ${status}`
+        );
+        return new _ApiError(msg, status, data);
+      }
+    }
+  }
+};
+var AuthenticationError = class extends ApiError {
+  constructor(message, response) {
+    super(message, 401, response, "NEXUS_AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends ApiError {
+  constructor(message, retryAfter, response) {
+    super(message, 429, response, "NEXUS_RATE_LIMIT_ERROR");
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message, details, response) {
+    super(message, 400, response, "NEXUS_VALIDATION_ERROR");
+    this.name = "ValidationError";
+    this.details = details;
+  }
+};
+var NotFoundError = class extends ApiError {
+  constructor(message, response) {
+    super(message, 404, response, "NEXUS_NOT_FOUND_ERROR");
+    this.name = "NotFoundError";
+  }
+};
+
+// src/http/cache.ts
+import { LRUCache } from "lru-cache";
+var CACHEABLE_POST_PATHS = /* @__PURE__ */ new Set([
+  "/context/retrieve",
+  "/memories/search",
+  "/knowledge/query"
+]);
+function isCacheablePost(path) {
+  return CACHEABLE_POST_PATHS.has(path);
+}
+function stableHash(value) {
+  const json = JSON.stringify(value, (_key, val) => {
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+      return Object.keys(val).sort().reduce((sorted, k) => {
+        sorted[k] = val[k];
+        return sorted;
+      }, {});
+    }
+    return val;
+  });
+  let hash = 5381;
+  for (let i = 0; i < json.length; i++) {
+    hash = (hash << 5) + hash + json.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+var CacheManager = class {
+  /**
+   * Create a new cache manager.
+   *
+   * @param config - Resolved cache configuration, or `false` to disable.
+   */
+  constructor(config) {
+    /** Running hit counter. */
+    this._hits = 0;
+    /** Running miss counter. */
+    this._misses = 0;
+    if (config === false) {
+      this.enabled = false;
+      this.cache = new LRUCache({ max: 1 });
+    } else {
+      this.enabled = true;
+      this.cache = new LRUCache({
+        max: config.max,
+        ttl: config.ttl * 1e3
+        // seconds -> milliseconds
+      });
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Key generation
+  // -----------------------------------------------------------------------
+  /**
+   * Generate a deterministic cache key from the request signature.
+   *
+   * Format: `METHOD:path:hash(params)`
+   *
+   * @param method - HTTP method (e.g. `GET`, `POST`).
+   * @param path   - Request path (e.g. `/memories/search`).
+   * @param params - Query parameters or request body (optional).
+   * @returns A string suitable for use as a cache key.
+   */
+  generateKey(method, path, params) {
+    const base = `${method.toUpperCase()}:${path}`;
+    if (params === void 0 || params === null) {
+      return base;
+    }
+    return `${base}:${stableHash(params)}`;
+  }
+  // -----------------------------------------------------------------------
+  // Core operations
+  // -----------------------------------------------------------------------
+  /**
+   * Retrieve a cached value.
+   *
+   * @typeParam T - Expected type of the cached value.
+   * @param key - Cache key (as returned by {@link generateKey}).
+   * @returns The cached value, or `undefined` on a miss.
+   */
+  get(key) {
+    if (!this.enabled) {
+      return void 0;
+    }
+    const value = this.cache.get(key);
+    if (value !== void 0) {
+      this._hits++;
+      return value;
+    }
+    this._misses++;
+    return void 0;
+  }
+  /**
+   * Store a value in the cache.
+   *
+   * @param key   - Cache key.
+   * @param value - Value to cache.
+   */
+  set(key, value) {
+    if (!this.enabled) {
+      return;
+    }
+    this.cache.set(key, value);
+  }
+  /**
+   * Invalidate all cache entries whose key contains the given pattern.
+   *
+   * This is typically called after a write operation to evict stale
+   * read results. For example, after `POST /memories`, calling
+   * `invalidate('/memories')` removes all cached memory queries.
+   *
+   * @param pattern - Substring to match against cache keys.
+   */
+  invalidate(pattern) {
+    if (!this.enabled) {
+      return;
+    }
+    for (const key of this.cache.keys()) {
+      if (key.includes(pattern)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+  /**
+   * Remove all entries from the cache and reset counters.
+   */
+  clear() {
+    if (!this.enabled) {
+      return;
+    }
+    this.cache.clear();
+    this._hits = 0;
+    this._misses = 0;
+  }
+  // -----------------------------------------------------------------------
+  // Observability
+  // -----------------------------------------------------------------------
+  /**
+   * Current cache statistics.
+   *
+   * Useful for logging, health checks, and dashboards.
+   */
+  get stats() {
+    return {
+      size: this.enabled ? this.cache.size : 0,
+      hits: this._hits,
+      misses: this._misses
+    };
+  }
+};
+
+// src/http/retry.ts
+var RetryManager = class {
+  /**
+   * Create a new retry manager.
+   *
+   * @param config - Fully-resolved retry settings, or `false` to disable retries entirely.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Determine whether a given error is eligible for retry.
+   *
+   * Retryable conditions:
+   * - {@link NetworkError} -- transient connectivity issues
+   * - {@link TimeoutError} -- request exceeded its deadline
+   * - {@link RateLimitError} (HTTP 429) -- server asks us to slow down
+   * - Any {@link ApiError} with a 5xx status code -- server-side failures
+   *
+   * Non-retryable conditions:
+   * - 4xx errors other than 429 (client errors that won't resolve on retry)
+   * - Cancelled / aborted requests
+   * - Any non-Nexus error (unknown failures are not assumed to be transient)
+   *
+   * @param error - The error to evaluate.
+   * @returns `true` if the operation should be retried.
+   */
+  isRetryable(error) {
+    if (error instanceof NetworkError) {
+      return true;
+    }
+    if (error instanceof TimeoutError) {
+      return true;
+    }
+    if (error instanceof RateLimitError) {
+      return true;
+    }
+    if (error instanceof ApiError) {
+      return error.statusCode >= 500 && error.statusCode < 600;
+    }
+    return false;
+  }
+  /**
+   * Calculate the delay (in milliseconds) before the next retry attempt.
+   *
+   * Uses exponential back-off: `delay = initialDelay * backoffFactor ^ attempt`.
+   *
+   * Special cases:
+   * - If the error is a {@link RateLimitError} with a `retryAfter` value,
+   *   that value (converted to ms) takes precedence over the computed delay.
+   * - A random jitter of ±10% is applied to prevent thundering herd.
+   * - The result is clamped to {@link ResolvedRetryConfig.maxDelay}.
+   *
+   * @param attempt - Zero-based attempt index (0 = first retry).
+   * @param error   - The error that triggered the retry (optional).
+   * @returns Delay in milliseconds before the next attempt.
+   */
+  getDelay(attempt, error) {
+    if (this.config === false) {
+      return 0;
+    }
+    const { initialDelay, backoffFactor, maxDelay } = this.config;
+    if (error instanceof RateLimitError && error.retryAfter != null) {
+      const serverDelay = error.retryAfter * 1e3;
+      return Math.min(this.applyJitter(serverDelay), maxDelay);
+    }
+    const exponentialDelay = initialDelay * Math.pow(backoffFactor, attempt);
+    return Math.min(this.applyJitter(exponentialDelay), maxDelay);
+  }
+  /**
+   * Execute an async function with automatic retries on transient failures.
+   *
+   * If retries are disabled (`config === false`), the function is invoked
+   * exactly once with no retry logic.
+   *
+   * @typeParam T - Return type of the wrapped function.
+   * @param fn - The async operation to execute (and potentially retry).
+   * @returns The resolved value of `fn`.
+   * @throws The last error encountered if all retry attempts are exhausted,
+   *         or immediately if the error is not retryable.
+   *
+   * @example
+   * ```typescript
+   * const manager = new RetryManager({ maxRetries: 3, initialDelay: 500, maxDelay: 5000, backoffFactor: 2 });
+   *
+   * const data = await manager.execute(async () => {
+   *   return fetch('/api/data').then(r => r.json());
+   * });
+   * ```
+   */
+  async execute(fn) {
+    if (this.config === false) {
+      return fn();
+    }
+    const { maxRetries } = this.config;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (!this.isRetryable(error)) {
+          throw error;
+        }
+        if (attempt >= maxRetries) {
+          throw error;
+        }
+        const delay = this.getDelay(attempt, error);
+        await this.sleep(delay);
+      }
+    }
+    throw lastError;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Apply ±10% random jitter to a delay value.
+   *
+   * @param delay - Base delay in milliseconds.
+   * @returns Jittered delay in milliseconds.
+   */
+  applyJitter(delay) {
+    const jitterFactor = 0.9 + Math.random() * 0.2;
+    return Math.round(delay * jitterFactor);
+  }
+  /**
+   * Sleep for the specified duration.
+   *
+   * @param ms - Duration in milliseconds.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/http/queue.ts
+var OfflineQueue = class {
+  /**
+   * Create a new offline queue.
+   *
+   * @param maxSize - Maximum number of requests to buffer. When the queue
+   *                  is full, subsequent {@link enqueue} calls will reject
+   *                  immediately. Defaults to `100`.
+   */
+  constructor(maxSize = 100) {
+    /** Internal FIFO queue of deferred requests. */
+    this.queue = [];
+    /** Guard flag to prevent concurrent flush operations. */
+    this.processing = false;
+    /** Auto-incrementing counter used to generate unique request IDs. */
+    this.idCounter = 0;
+    this.maxSize = maxSize;
+  }
+  /**
+   * Add a request to the queue.
+   *
+   * The returned `Promise` settles only when the request is eventually
+   * executed during a {@link flush} call.
+   *
+   * @param request - The request descriptor (method, path, and optional data).
+   * @returns A `Promise` that resolves with the executor's return value
+   *          once the request is flushed, or rejects if the queue is full
+   *          or the executor fails.
+   *
+   * @throws {NexusError} If the queue has reached its maximum capacity.
+   */
+  enqueue(request) {
+    if (this.queue.length >= this.maxSize) {
+      return Promise.reject(
+        new NexusError(
+          `Offline queue is full (max ${this.maxSize}). Request to ${request.method} ${request.path} was rejected.`,
+          "NEXUS_QUEUE_FULL"
+        )
+      );
+    }
+    return new Promise((resolve, reject) => {
+      this.idCounter += 1;
+      const queued = {
+        id: `oq_${this.idCounter}_${Date.now()}`,
+        method: request.method,
+        path: request.path,
+        data: request.data,
+        resolve,
+        reject,
+        timestamp: Date.now()
+      };
+      this.queue.push(queued);
+    });
+  }
+  /**
+   * Process all queued requests in FIFO order.
+   *
+   * Each request is passed to the provided `executor` function. On success
+   * the caller's deferred promise is resolved; on failure it is rejected.
+   *
+   * Requests are processed sequentially to preserve ordering guarantees.
+   * If a flush is already in progress, subsequent calls are silently ignored.
+   *
+   * @param executor - An async function that performs the actual HTTP call
+   *                   for a given queued request and returns the response.
+   *
+   * @example
+   * ```typescript
+   * await queue.flush(async (req) => {
+   *   return httpClient.request(req.method, req.path, req.data);
+   * });
+   * ```
+   */
+  async flush(executor) {
+    if (this.processing) {
+      return;
+    }
+    this.processing = true;
+    try {
+      while (this.queue.length > 0) {
+        const request = this.queue.shift();
+        try {
+          const result = await executor(request);
+          request.resolve(result);
+        } catch (error) {
+          request.reject(error);
+        }
+      }
+    } finally {
+      this.processing = false;
+    }
+  }
+  /**
+   * The number of requests currently waiting in the queue.
+   */
+  get size() {
+    return this.queue.length;
+  }
+  /**
+   * Remove all pending requests from the queue.
+   *
+   * Every deferred promise is rejected with a cancellation error so that
+   * callers are not left hanging indefinitely.
+   */
+  clear() {
+    while (this.queue.length > 0) {
+      const request = this.queue.shift();
+      request.reject(
+        new NexusError(
+          "Request cancelled: offline queue was cleared.",
+          "NEXUS_QUEUE_CLEARED"
+        )
+      );
+    }
+  }
+};
+
+// src/http/client.ts
+var HttpClient = class {
+  /**
+   * Create a new HTTP client.
+   *
+   * @param config - Fully-resolved SDK configuration (see {@link resolveConfig}).
+   */
+  constructor(config) {
+    /** Whether the client is currently considered online. */
+    this._isOnline = true;
+    this.config = config;
+    this.cache = new CacheManager(config.cache);
+    this.retry = new RetryManager(config.retry);
+    if (config.offline?.enabled) {
+      this.offlineQueue = new OfflineQueue(config.offline.maxQueueSize ?? 100);
+    }
+    this.axios = axios.create({
+      baseURL: config.baseUrl,
+      timeout: config.timeout
+    });
+    this.setupRequestInterceptor();
+    this.setupResponseInterceptor();
+  }
+  // -----------------------------------------------------------------------
+  // Offline queue support
+  // -----------------------------------------------------------------------
+  /**
+   * Set the online/offline status of the client.
+   *
+   * When transitioning from offline to online, the queued requests are
+   * automatically flushed.
+   *
+   * @param online - `true` if the client is online, `false` if offline.
+   */
+  setOnline(online) {
+    const wasOffline = !this._isOnline;
+    this._isOnline = online;
+    if (wasOffline && online && this.offlineQueue) {
+      void this.offlineQueue.flush(async (req) => {
+        switch (req.method) {
+          case "POST":
+            return this.post(req.path, req.data);
+          case "PUT":
+            return this.put(req.path, req.data);
+          case "PATCH":
+            return this.patch(req.path, req.data);
+          case "DELETE":
+            return this.delete(req.path);
+          default:
+            return this.get(req.path);
+        }
+      });
+    }
+  }
+  /**
+   * Access the offline queue instance (if offline mode is enabled).
+   */
+  get queue() {
+    return this.offlineQueue;
+  }
+  // -----------------------------------------------------------------------
+  // Public request methods
+  // -----------------------------------------------------------------------
+  /**
+   * Send a GET request.
+   *
+   * @typeParam T - Expected shape of the response body.
+   * @param path   - URL path relative to the base URL (e.g. `/memory/search`).
+   * @param params - Optional query parameters.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The parsed response body.
+   */
+  async get(path, params, signal) {
+    const cacheKey = this.cache.generateKey("GET", path, params);
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0) return cached;
+    const result = await this.retry.execute(async () => {
+      const response = await this.axios.get(path, { params, signal });
+      return response.data;
+    });
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+  /**
+   * Send a POST request.
+   *
+   * @typeParam T - Expected shape of the response body.
+   * @param path   - URL path relative to the base URL.
+   * @param data   - Optional request body.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The parsed response body.
+   */
+  async post(path, data, signal) {
+    if (this.offlineQueue && !this._isOnline) {
+      return this.offlineQueue.enqueue({ method: "POST", path, data });
+    }
+    if (isCacheablePost(path)) {
+      const cacheKey = this.cache.generateKey("POST", path, data);
+      const cached = this.cache.get(cacheKey);
+      if (cached !== void 0) return cached;
+      const result2 = await this.retry.execute(async () => {
+        const response = await this.axios.post(path, data, { signal });
+        return response.data;
+      });
+      this.cache.set(cacheKey, result2);
+      return result2;
+    }
+    const result = await this.retry.execute(async () => {
+      const response = await this.axios.post(path, data, { signal });
+      return response.data;
+    });
+    this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
+    return result;
+  }
+  /**
+   * Send a PUT request.
+   *
+   * @typeParam T - Expected shape of the response body.
+   * @param path   - URL path relative to the base URL.
+   * @param data   - Optional request body.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The parsed response body.
+   */
+  async put(path, data, signal) {
+    if (this.offlineQueue && !this._isOnline) {
+      return this.offlineQueue.enqueue({ method: "PUT", path, data });
+    }
+    const result = await this.retry.execute(async () => {
+      const response = await this.axios.put(path, data, { signal });
+      return response.data;
+    });
+    this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
+    return result;
+  }
+  /**
+   * Send a PATCH request.
+   *
+   * @typeParam T - Expected shape of the response body.
+   * @param path   - URL path relative to the base URL.
+   * @param data   - Optional request body.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The parsed response body.
+   */
+  async patch(path, data, signal) {
+    if (this.offlineQueue && !this._isOnline) {
+      return this.offlineQueue.enqueue({ method: "PATCH", path, data });
+    }
+    const result = await this.retry.execute(async () => {
+      const response = await this.axios.patch(path, data, { signal });
+      return response.data;
+    });
+    this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
+    return result;
+  }
+  /**
+   * Send a DELETE request.
+   *
+   * @typeParam T - Expected shape of the response body.
+   * @param path   - URL path relative to the base URL.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The parsed response body.
+   */
+  async delete(path, signal) {
+    if (this.offlineQueue && !this._isOnline) {
+      return this.offlineQueue.enqueue({ method: "DELETE", path });
+    }
+    const result = await this.retry.execute(async () => {
+      const response = await this.axios.delete(path, { signal });
+      return response.data;
+    });
+    this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
+    return result;
+  }
+  // -----------------------------------------------------------------------
+  // Interceptors
+  // -----------------------------------------------------------------------
+  /**
+   * Attach the request interceptor.
+   *
+   * Responsibilities:
+   * - Set `X-API-Key` authentication header.
+   * - Set `X-Tenant-ID` header when a tenant identifier is configured.
+   * - Ensure `Content-Type` is `application/json`.
+   */
+  setupRequestInterceptor() {
+    this.axios.interceptors.request.use((requestConfig) => {
+      requestConfig.headers.set("X-API-Key", this.config.apiKey);
+      if (this.config.tenantId) {
+        requestConfig.headers.set("X-Tenant-ID", this.config.tenantId);
+      }
+      requestConfig.headers.set("Content-Type", "application/json");
+      return requestConfig;
+    });
+  }
+  /**
+   * Attach the response interceptor.
+   *
+   * Successful responses pass through unchanged. Errors are normalised
+   * into the appropriate {@link NexusError} subclass:
+   *
+   * | Condition              | Error class        |
+   * |------------------------|--------------------|
+   * | Request cancelled      | *(re-thrown as-is)*|
+   * | Timeout (`ECONNABORTED`, `ETIMEDOUT`) | {@link TimeoutError}  |
+   * | No response received   | {@link NetworkError}  |
+   * | HTTP 4xx / 5xx         | {@link ApiError} (or subclass) |
+   */
+  setupResponseInterceptor() {
+    this.axios.interceptors.response.use(
+      // Success handler -- pass through
+      (response) => response,
+      // Error handler -- normalise into NexusError hierarchy
+      (error) => {
+        if (axios.isCancel(error)) {
+          return Promise.reject(error);
+        }
+        if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+          return Promise.reject(
+            new TimeoutError(
+              `Request to ${error.config?.url ?? "unknown"} timed out after ${this.config.timeout}ms`,
+              error
+            )
+          );
+        }
+        if (error.response) {
+          const apiError = ApiError.fromResponse(error.response);
+          const reqUrl = error.config?.url ?? "";
+          if (this.onApiError && !reqUrl.includes("/errors")) {
+            try {
+              this.onApiError(
+                error.response.status,
+                error.config?.method?.toUpperCase() ?? "UNKNOWN",
+                reqUrl,
+                apiError.message
+              );
+            } catch {
+            }
+          }
+          return Promise.reject(apiError);
+        }
+        return Promise.reject(
+          new NetworkError(
+            error.message || "A network error occurred",
+            error
+          )
+        );
+      }
+    );
+  }
+};
+
+// src/services/base.ts
+var BaseService = class {
+  /**
+   * @param http - Fully-configured {@link HttpClient} instance.
+   */
+  constructor(http) {
+    this.http = http;
+  }
+};
+
+// src/types/context.ts
+var DEPTH_PRESETS = {
+  L0: { include_profile: true, profile_limit: 1, include_history: false, include_graph: false, layers: [] },
+  L1: { include_profile: true, profile_limit: 3, include_history: false, include_graph: false, layers: [] },
+  L2: { include_profile: true, profile_limit: 10, include_history: false, include_graph: false, layers: ["semantic"] },
+  L3: { include_profile: true, profile_limit: 20, include_history: true, include_graph: true, layers: ["semantic", "graph"] }
+};
+
+// src/schemas/context.ts
+import { z } from "zod";
+var contextLayerSchema = z.enum(["recent", "semantic", "graph"]);
+var contextRequestSchema = z.object({
+  user_id: z.string().min(1),
+  query: z.string().optional(),
+  layers: z.array(contextLayerSchema).optional(),
+  recent_hours: z.number().positive().optional(),
+  recent_limit: z.number().int().positive().optional(),
+  include_profile: z.boolean().optional(),
+  profile_limit: z.number().int().positive().optional(),
+  include_history: z.boolean().optional(),
+  history_limit: z.number().int().positive().optional(),
+  include_graph: z.boolean().optional(),
+  graph_limit: z.number().int().positive().optional(),
+  // RFC 3339 with required timezone offset (`offset: true`). Rejects naive
+  // datetimes like `"2026-01-01T00:00:00"` to surface ingest-boundary
+  // ambiguity early — see ContextRequest.as_of JSDoc.
+  // Added in v1.3.0 (US-037 Wave 1 TASK-005).
+  as_of: z.string().datetime({ offset: true }).optional()
+});
+
+// src/errors/validation.ts
+var InputValidationError = class extends NexusError {
+  constructor(zodError) {
+    const message = `Validation failed: ${zodError.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")}`;
+    super(message, "NEXUS_INPUT_VALIDATION_ERROR");
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "InputValidationError";
+    this.fieldErrors = zodError.flatten().fieldErrors;
+  }
+};
+
+// src/services/context.ts
+var ContextService = class extends BaseService {
+  /**
+   * Retrieve aggregated context for a user across multiple layers.
+   *
+   * Performs v2.0 three-layer parallel retrieval:
+   * - **recent**: Time-anchored activities from the activity stream
+   * - **semantic**: Vector similarity search against Mem0 memory store
+   * - **graph**: Knowledge graph traversal via Fast GraphRAG
+   *
+   * @param request - Context retrieval parameters including user_id, query, and layer configuration.
+   * @returns Aggregated context containing profile, history, graph, and performance metadata.
+   */
+  async retrieve(request, options) {
+    let resolved;
+    if (request.depth !== void 0 && DEPTH_PRESETS[request.depth]) {
+      const { depth, ...rest } = request;
+      resolved = { ...DEPTH_PRESETS[depth], ...rest };
+    } else {
+      const { depth: _depth, ...rest } = request;
+      resolved = rest;
+    }
+    const parsed = contextRequestSchema.safeParse(resolved);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/context/retrieve", resolved, options?.signal);
+  }
+};
+
+// src/schemas/memory.ts
+import { z as z2 } from "zod";
+var memoryTypeSchema = z2.enum(["episodic", "semantic", "procedural"]);
+var memoryCreateSchema = z2.object({
+  user_id: z2.string().min(1),
+  content: z2.string().min(1).max(1e4),
+  memory_type: memoryTypeSchema.optional(),
+  metadata: z2.record(z2.unknown()).optional()
+});
+var memoryUpdateSchema = z2.object({
+  content: z2.string().optional(),
+  memory_type: memoryTypeSchema.optional(),
+  metadata: z2.record(z2.unknown()).optional()
+});
+var memorySearchSchema = z2.object({
+  user_id: z2.string().min(1),
+  query: z2.string().min(1),
+  memory_type: memoryTypeSchema.optional(),
+  limit: z2.number().int().min(1).max(50).optional(),
+  threshold: z2.number().min(0).max(1).optional()
+});
+
+// src/services/memories.ts
+var MemoryService = class extends BaseService {
+  /**
+   * Create a new memory record.
+   *
+   * @param data - Memory creation payload including user_id, content, and optional type/metadata.
+   * @returns The newly created memory with generated ID and timestamps.
+   */
+  async create(data, options) {
+    const parsed = memoryCreateSchema.safeParse(data);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/memories", data, options?.signal);
+  }
+  /**
+   * List memories with optional filtering and pagination.
+   *
+   * @param params - Optional filters for user_id, memory_type, and pagination controls.
+   * @returns Paginated list of memory records.
+   */
+  async list(params, options) {
+    return this.http.get("/memories", params, options?.signal);
+  }
+  /**
+   * Retrieve a single memory by its ID.
+   *
+   * @param memoryId - UUID of the memory to retrieve.
+   * @returns The memory record.
+   * @throws {ApiError} 404 if the memory does not exist.
+   */
+  async get(memoryId, options) {
+    return this.http.get(`/memories/${memoryId}`, void 0, options?.signal);
+  }
+  /**
+   * Update an existing memory record.
+   *
+   * Supports partial updates -- only the provided fields are modified.
+   *
+   * @param memoryId - UUID of the memory to update.
+   * @param data - Fields to update (content, memory_type, metadata).
+   * @returns The updated memory record.
+   * @throws {ApiError} 404 if the memory does not exist.
+   */
+  async update(memoryId, data, options) {
+    const parsed = memoryUpdateSchema.safeParse(data);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.patch(`/memories/${memoryId}`, data, options?.signal);
+  }
+  /**
+   * Delete a memory record.
+   *
+   * @param memoryId - UUID of the memory to delete.
+   * @throws {ApiError} 404 if the memory does not exist.
+   */
+  async delete(memoryId, options) {
+    return this.http.delete(`/memories/${memoryId}`, options?.signal);
+  }
+  /**
+   * Perform semantic similarity search across memories.
+   *
+   * Uses Mem0's vector search to find memories relevant to the query text.
+   * Results are ranked by similarity score and filtered by optional thresholds.
+   *
+   * @param request - Search parameters including user_id, query, and optional filters.
+   * @returns Search results with scored memories and timing metadata.
+   */
+  async search(request, options) {
+    const parsed = memorySearchSchema.safeParse(request);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/memories/search", request, options?.signal);
+  }
+  /**
+   * Retrieve the Memory Journal view (US-015).
+   *
+   * Groups memories chronologically by date for review. Supports both
+   * markdown (human-readable) and JSON (programmatic) output formats.
+   *
+   * @param params - Optional filters for format, date range, and user_id.
+   * @returns Journal response with memories grouped by date.
+   */
+  async journal(params, options) {
+    return this.http.get("/memories/journal", params, options?.signal);
+  }
+};
+
+// src/schemas/conversation.ts
+import { z as z3 } from "zod";
+var messageRoleSchema = z3.enum(["user", "assistant", "system", "tool"]);
+var conversationCreateSchema = z3.object({
+  user_id: z3.string().min(1),
+  session_id: z3.string().optional(),
+  metadata: z3.record(z3.unknown()).optional()
+});
+var messageCreateSchema = z3.object({
+  role: messageRoleSchema,
+  content: z3.string().min(1).max(5e4),
+  metadata: z3.record(z3.unknown()).optional()
+});
+
+// src/services/conversations.ts
+var ConversationService = class extends BaseService {
+  /**
+   * Create a new conversation session.
+   *
+   * @param data - Conversation creation payload including user_id and optional metadata.
+   * @returns The newly created conversation with generated ID and timestamps.
+   */
+  async create(data, options) {
+    const parsed = conversationCreateSchema.safeParse(data);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/conversations", data, options?.signal);
+  }
+  /**
+   * List conversations with optional filtering and pagination.
+   *
+   * @param params - Optional filters for user_id and pagination controls.
+   * @returns Paginated list of conversation records.
+   */
+  async list(params, options) {
+    return this.http.get("/conversations", params, options?.signal);
+  }
+  /**
+   * Retrieve a conversation with its messages included.
+   *
+   * @param conversationId - UUID of the conversation to retrieve.
+   * @returns Conversation detail including the full message list.
+   * @throws {ApiError} 404 if the conversation does not exist.
+   */
+  async get(conversationId, options) {
+    return this.http.get(`/conversations/${conversationId}`, void 0, options?.signal);
+  }
+  /**
+   * Add a message to an existing conversation.
+   *
+   * The message is appended to the conversation's message sequence.
+   * Zep will asynchronously update the conversation summary after
+   * new messages are added.
+   *
+   * @param conversationId - UUID of the target conversation.
+   * @param message - Message payload including role and content.
+   * @returns The newly created message with generated ID and sequence number.
+   * @throws {ApiError} 404 if the conversation does not exist.
+   */
+  async addMessage(conversationId, message, options) {
+    const parsed = messageCreateSchema.safeParse(message);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post(`/conversations/${conversationId}/messages`, message, options?.signal);
+  }
+  /**
+   * List messages within a conversation with optional pagination.
+   *
+   * Messages are returned in chronological order (oldest first).
+   *
+   * @param conversationId - UUID of the conversation.
+   * @param params - Optional pagination controls (limit, offset).
+   * @returns Paginated list of messages.
+   * @throws {ApiError} 404 if the conversation does not exist.
+   */
+  async getMessages(conversationId, params, options) {
+    return this.http.get(
+      `/conversations/${conversationId}/messages`,
+      params,
+      options?.signal
+    );
+  }
+  /**
+   * Retrieve the auto-generated summary of a conversation.
+   *
+   * Summaries are produced by Zep OSS temporal graph analysis and
+   * include key points extracted from the conversation history.
+   *
+   * @param conversationId - UUID of the conversation.
+   * @returns The conversation summary with key points and generation timestamp.
+   * @throws {ApiError} 404 if the conversation does not exist.
+   */
+  async getSummary(conversationId, options) {
+    return this.http.get(`/conversations/${conversationId}/summary`, void 0, options?.signal);
+  }
+  /**
+   * Delete a conversation and all its messages.
+   *
+   * This operation is irreversible. The conversation, all associated
+   * messages, and the generated summary will be permanently removed.
+   *
+   * @param conversationId - UUID of the conversation to delete.
+   * @throws {ApiError} 404 if the conversation does not exist.
+   */
+  async delete(conversationId, options) {
+    return this.http.delete(`/conversations/${conversationId}`, options?.signal);
+  }
+};
+
+// src/schemas/knowledge.ts
+import { z as z4 } from "zod";
+var entityCreateSchema = z4.object({
+  name: z4.string().min(1),
+  entity_type: z4.string().min(1),
+  description: z4.string().optional(),
+  properties: z4.record(z4.unknown()).optional()
+});
+var graphQueryRequestSchema = z4.object({
+  entity_name: z4.string().min(1),
+  depth: z4.number().int().min(1).max(3).optional(),
+  relationship_types: z4.array(z4.string()).optional()
+});
+var extractionRequestSchema = z4.object({
+  text: z4.string().min(1).max(1e4),
+  agent_id: z4.string().optional(),
+  owner_user_id: z4.string().optional()
+});
+
+// src/services/knowledge.ts
+var KnowledgeService = class extends BaseService {
+  /**
+   * Create a new knowledge entity in the graph.
+   *
+   * @param data - Entity creation payload including name, type, and optional description/properties.
+   * @returns The newly created entity with generated entity_id.
+   */
+  async createEntity(data, options) {
+    const parsed = entityCreateSchema.safeParse(data);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/knowledge/entities", data, options?.signal);
+  }
+  /**
+   * List knowledge entities with optional filtering.
+   *
+   * @param params - Optional filters for user_id, entity_type, and pagination controls.
+   * @returns Paginated list of knowledge entities.
+   */
+  async listEntities(params, options) {
+    return this.http.get("/knowledge/entities", params, options?.signal);
+  }
+  /**
+   * Query the knowledge graph using BFS traversal.
+   *
+   * Starts from a named entity and traverses outward up to the specified
+   * depth, collecting all reachable entities and relationships along
+   * the traversal paths.
+   *
+   * @param request - Graph query parameters including starting entity name, depth, and optional relationship type filters.
+   * @returns Graph query response with the start entity, traversal paths, and total path count.
+   */
+  async query(request, options) {
+    const parsed = graphQueryRequestSchema.safeParse(request);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/knowledge/query", request, options?.signal);
+  }
+  /**
+   * Extract entities and relationships from unstructured text.
+   *
+   * Uses Fast GraphRAG's NLP pipeline to identify named entities and
+   * their relationships in Triplex format (Subject, Relation, Object).
+   * Extracted items are automatically persisted to the knowledge graph.
+   *
+   * @param request - Extraction request including the source text and ownership (agent_id or owner_user_id).
+   * @returns Extraction result with lists of created entities and relationships.
+   */
+  async extract(request, options) {
+    const parsed = extractionRequestSchema.safeParse(request);
+    if (!parsed.success) {
+      throw new InputValidationError(parsed.error);
+    }
+    return this.http.post("/knowledge/extract", request, options?.signal);
+  }
+};
+
+// src/services/activities.ts
+var ActivityService = class extends BaseService {
+  /**
+   * Batch-ingest an activity stream.
+   *
+   * Accepts up to 1000 activities per request. Activities are queued for
+   * asynchronous processing by Arq workers on the Nexus backend.
+   *
+   * @param request - The activity stream payload containing agent ID and activities.
+   * @returns Processing summary with accepted / processed / queued counts.
+   */
+  async stream(request, options) {
+    return this.http.post("/activities/stream", request, options?.signal);
+  }
+  /**
+   * Convenience method to log a single activity.
+   *
+   * Wraps {@link stream} for the common case of reporting one event at a time.
+   *
+   * @param activity  - The activity event to record.
+   * @param agentId   - Agent identifier (defaults to `'default'`).
+   * @returns Processing summary with accepted / processed / queued counts.
+   */
+  async log(activity, agentId, options) {
+    return this.stream({
+      agent_id: agentId || "default",
+      activities: [activity]
+    }, options);
+  }
+};
+
+// src/services/tenants.ts
+var TenantService = class extends BaseService {
+  /**
+   * Retrieve the current tenant's profile.
+   *
+   * Returns the tenant record associated with the API key,
+   * including name, tier, quotas, and current usage snapshot.
+   *
+   * @returns The authenticated tenant's profile.
+   */
+  async me(options) {
+    return this.http.get("/tenants/me", void 0, options?.signal);
+  }
+  /**
+   * Retrieve the current tenant's resource usage statistics.
+   *
+   * Returns counts for memories, conversations, and today's API calls.
+   * Useful for monitoring quota consumption and building dashboards.
+   *
+   * @returns Current resource usage for the authenticated tenant.
+   */
+  async usage(options) {
+    return this.http.get("/tenants/me/usage", void 0, options?.signal);
+  }
+  /**
+   * List all API keys for the current tenant.
+   *
+   * @returns Array of API key records (without full key values).
+   */
+  async listApiKeys(options) {
+    return this.http.get("/tenants/me/api-keys", void 0, options?.signal);
+  }
+  /**
+   * Create a new API key for the current tenant.
+   *
+   * @param data - API key creation parameters (name, scopes, expiry).
+   * @returns The newly created API key, including the full key value (shown only once).
+   */
+  async createApiKey(data, options) {
+    return this.http.post("/tenants/me/api-keys", data, options?.signal);
+  }
+  /**
+   * Revoke (delete) an API key.
+   *
+   * @param id - The UUID of the API key to revoke.
+   */
+  async revokeApiKey(id, options) {
+    return this.http.delete(`/tenants/me/api-keys/${id}`, options?.signal);
+  }
+};
+
+// src/services/feedback.ts
+var FeedbackService = class extends BaseService {
+  /**
+   * Submit explicit feedback for a prior context retrieval (L2 signal).
+   *
+   * The backend accepts the submission immediately (HTTP 202) and processes
+   * quality scoring asynchronously via QualityScoreWorker.
+   *
+   * @param retrieveId - The `retrieve_id` returned by `/context/retrieve`.
+   * @param data       - Rating and optional per-item feedback.
+   * @param options    - Optional request options (e.g. AbortSignal).
+   * @returns The created feedback record metadata.
+   */
+  async submit(retrieveId, data, options) {
+    return this.http.put(
+      `/feedback/${retrieveId}`,
+      data,
+      options?.signal
+    );
+  }
+  /**
+   * List feedback records with optional filtering and pagination.
+   *
+   * @param params  - Optional filters: `user_id`, `limit`, `offset`.
+   * @param options - Optional request options (e.g. AbortSignal).
+   * @returns Paginated list of feedback records.
+   */
+  async list(params, options) {
+    const query = new URLSearchParams();
+    if (params?.user_id) query.set("user_id", params.user_id);
+    if (params?.limit !== void 0) query.set("limit", String(params.limit));
+    if (params?.offset !== void 0) query.set("offset", String(params.offset));
+    const qs = query.toString();
+    return this.http.get(
+      `/feedback${qs ? `?${qs}` : ""}`,
+      void 0,
+      options?.signal
+    );
+  }
+};
+
+// src/services/errors.ts
+var ErrorService = class extends BaseService {
+  /**
+   * Submit a structured error report.
+   *
+   * @param data    - Error report payload.
+   * @param options - Optional request options (e.g. AbortSignal).
+   * @returns The created or updated error report metadata.
+   */
+  async submit(data, options) {
+    return this.http.post(
+      "/errors",
+      data,
+      options?.signal
+    );
+  }
+};
+
+// src/client.ts
+var NexusClient = class {
+  /**
+   * Create a new Nexus SDK client.
+   *
+   * @param config - SDK configuration. Only `apiKey` is required; all other
+   *   fields fall back to sensible defaults (see {@link resolveConfig}).
+   *
+   * @throws {Error} If `apiKey` is missing or empty.
+   */
+  constructor(config) {
+    const resolved = resolveConfig(config);
+    this.http = new HttpClient(resolved);
+    this.context = new ContextService(this.http);
+    this.memories = new MemoryService(this.http);
+    this.conversations = new ConversationService(this.http);
+    this.knowledge = new KnowledgeService(this.http);
+    this.activities = new ActivityService(this.http);
+    this.tenants = new TenantService(this.http);
+    this.feedback = new FeedbackService(this.http);
+    this.errors = new ErrorService(this.http);
+    if (resolved.autoErrorReport) {
+      this.http.onApiError = (statusCode, method, url, detail) => {
+        this.errors.submit({
+          error_type: "api_error",
+          severity: statusCode >= 500 ? "major" : "minor",
+          description: `${method} ${url} \u2192 ${statusCode}: ${detail}`,
+          request_context: { method, url, status_code: statusCode }
+        }).catch(() => {
+        });
+      };
+    }
+  }
+  /**
+   * Access the offline queue instance (if offline mode is enabled).
+   */
+  get queue() {
+    return this.http.queue;
+  }
+  /**
+   * Set the online/offline status of the client.
+   *
+   * When transitioning from offline to online, queued requests are
+   * automatically flushed.
+   */
+  setOnline(online) {
+    this.http.setOnline(online);
+  }
+};
+
+// src/schemas/tenant.ts
+import { z as z5 } from "zod";
+var apiKeyScopeSchema = z5.enum(["read", "write", "admin"]);
+var apiKeyCreateSchema = z5.object({
+  name: z5.string().min(1).max(100),
+  scopes: z5.array(apiKeyScopeSchema).optional(),
+  expires_days: z5.number().int().min(1).max(365).optional()
+});
+export {
+  ActivityService,
+  ApiError,
+  AuthenticationError,
+  ConfigurationError,
+  ContextService,
+  ConversationService,
+  DEFAULT_CONFIG,
+  DEPTH_PRESETS,
+  ErrorService,
+  FeedbackService,
+  InputValidationError,
+  KnowledgeService,
+  MemoryService,
+  NetworkError,
+  NexusClient,
+  NexusError,
+  NotFoundError,
+  OfflineQueue,
+  RateLimitError,
+  TenantService,
+  TimeoutError,
+  ValidationError,
+  apiKeyCreateSchema,
+  contextRequestSchema,
+  conversationCreateSchema,
+  entityCreateSchema,
+  extractionRequestSchema,
+  graphQueryRequestSchema,
+  memoryCreateSchema,
+  memorySearchSchema,
+  memoryUpdateSchema,
+  messageCreateSchema,
+  resolveConfig
+};
+//# sourceMappingURL=index.mjs.map