@nexusm/sdk 5.1.0 → 5.2.0

package/dist/index.d.mts

@@ -360,25 +360,6 @@ declare class OfflineQueue {
  * every failure surfaces as a typed {@link NexusError} subclass.
  */
 
-/**
- * HTTP client that communicates with the Nexus API.
- *
- * All service-level modules (Memory, Conversation, Knowledge, Context)
- * delegate their network calls to a shared `HttpClient` instance, which
- * guarantees consistent authentication, timeout handling, and error
- * mapping across the entire SDK surface.
- *
- * @example
- * ```typescript
- * import { resolveConfig } from '../config';
- * import { HttpClient } from './client';
- *
- * const config = resolveConfig({ apiKey: 'nx_test_abc123' });
- * const http = new HttpClient(config);
- *
- * const memories = await http.get<Memory[]>('/memory/search', { query: 'hello' });
- * ```
- */
 declare class HttpClient {
     /** Underlying Axios instance. */
     private readonly axios;
@@ -2649,6 +2630,25 @@ declare class ValidationError extends ApiError {
 /**
  * HTTP 404 -- the requested resource does not exist.
  */
+/**
+ * Something between the caller and the Nexus API answered the request.
+ *
+ * Raised for two shapes that are otherwise indistinguishable from success:
+ *
+ * 1. a **3xx redirect** (auth edges such as Cloudflare Access bounce
+ *    unauthenticated calls to a login page), and
+ * 2. a **2xx whose body is not JSON** on a call that expects JSON
+ *    (a captive portal or proxy returning its own HTML with status 200).
+ *
+ * Both used to resolve successfully with an HTML string as `data`, which a
+ * caller's `result.results ?? []` turns into "zero results" — Kairos logged
+ * "connected" for two months while Nexus recorded zero calls
+ * (Kairos#66 / Aether#372). A wrong credential must fail loudly, not
+ * quietly look like an empty database.
+ */
+declare class UpstreamInterceptError extends ApiError {
+    constructor(message: string, statusCode: number, response?: unknown);
+}
 declare class NotFoundError extends ApiError {
     constructor(message: string, response?: unknown);
 }
@@ -2820,4 +2820,4 @@ declare const apiKeyCreateSchema: z.ZodObject<{
     expires_in_days?: number | undefined;
 }>;
 
-export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };
+export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, UpstreamInterceptError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };

package/dist/index.d.ts

@@ -360,25 +360,6 @@ declare class OfflineQueue {
  * every failure surfaces as a typed {@link NexusError} subclass.
  */
 
-/**
- * HTTP client that communicates with the Nexus API.
- *
- * All service-level modules (Memory, Conversation, Knowledge, Context)
- * delegate their network calls to a shared `HttpClient` instance, which
- * guarantees consistent authentication, timeout handling, and error
- * mapping across the entire SDK surface.
- *
- * @example
- * ```typescript
- * import { resolveConfig } from '../config';
- * import { HttpClient } from './client';
- *
- * const config = resolveConfig({ apiKey: 'nx_test_abc123' });
- * const http = new HttpClient(config);
- *
- * const memories = await http.get<Memory[]>('/memory/search', { query: 'hello' });
- * ```
- */
 declare class HttpClient {
     /** Underlying Axios instance. */
     private readonly axios;
@@ -2649,6 +2630,25 @@ declare class ValidationError extends ApiError {
 /**
  * HTTP 404 -- the requested resource does not exist.
  */
+/**
+ * Something between the caller and the Nexus API answered the request.
+ *
+ * Raised for two shapes that are otherwise indistinguishable from success:
+ *
+ * 1. a **3xx redirect** (auth edges such as Cloudflare Access bounce
+ *    unauthenticated calls to a login page), and
+ * 2. a **2xx whose body is not JSON** on a call that expects JSON
+ *    (a captive portal or proxy returning its own HTML with status 200).
+ *
+ * Both used to resolve successfully with an HTML string as `data`, which a
+ * caller's `result.results ?? []` turns into "zero results" — Kairos logged
+ * "connected" for two months while Nexus recorded zero calls
+ * (Kairos#66 / Aether#372). A wrong credential must fail loudly, not
+ * quietly look like an empty database.
+ */
+declare class UpstreamInterceptError extends ApiError {
+    constructor(message: string, statusCode: number, response?: unknown);
+}
 declare class NotFoundError extends ApiError {
     constructor(message: string, response?: unknown);
 }
@@ -2820,4 +2820,4 @@ declare const apiKeyCreateSchema: z.ZodObject<{
     expires_in_days?: number | undefined;
 }>;
 
-export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };
+export { type Activity, type ActivityProcessingStatus, ActivityService, type ActivityStats, type ActivityStatusResponse, type ActivityStreamRequest, type ActivityStreamResponse, type ActivityType, ApiError, type ApiErrorDetail, type ApiKey, type ApiKeyCreate, type ApiKeyCreated, type ApiResponse, AuthenticationError, type CacheConfig, type CompoundId, ConfigurationError, type ContextDepth, type ContextDepthPreset, type ContextGraphEntity, type ContextLayer, type ContextRequest, type ContextRetrieveResponse, ContextService, type Conversation, type ConversationCreate, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityListParams, type EntityListResponse, type ErrorReportRequest, type ErrorReportResponse, ErrorService, type ErrorSeverity, type ErrorType, type ExtractionRequest, type ExtractionResult, type FeedbackItemRequest, type FeedbackListItem, type FeedbackListParams, type FeedbackListResponse, type FeedbackResponse, FeedbackService, type FeedbackSubmitRequest, type GraphPath, type GraphPathEntity, type GraphPathRelationship, type GraphQueryRequest, type GraphQueryResponse, type HealthResponse, type HealthStatus, InputValidationError, type JournalEntry, type JournalResponse, type KnowledgeEntity, type KnowledgeRelationship, KnowledgeService, type Memory, type MemoryCreate, type MemoryJournalParams, type MemoryList, type MemoryListParams, type MemorySearch, type MemorySearchResult, MemoryService, type MemoryType, type MemoryUpdate, type Message, type MessageCreate, type MessageList, type MessageListParams, type MessageRole, NetworkError, NexusClient, type NexusConfig, NexusError, NotFoundError, type OfflineConfig, OfflineQueue, type PaginatedResponse, type Pagination, type ProfileMemory, type QueuedRequest, RateLimitError, type RequestOptions, type ResolvedCacheConfig, type ResolvedConfig, type ResolvedRetryConfig, type RetryConfig, type SearchResult, type ServiceStatus, type SortOrder, type Tenant, type TenantQuotas, TenantService, type TenantTier, TimeoutError, UpstreamInterceptError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, extractionRequestSchema, graphQueryRequestSchema, memoryCreateSchema, memorySearchSchema, memoryUpdateSchema, messageCreateSchema, resolveConfig };

package/dist/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   RateLimitError: () => RateLimitError,
   TenantService: () => TenantService,
   TimeoutError: () => TimeoutError,
+  UpstreamInterceptError: () => UpstreamInterceptError,
   ValidationError: () => ValidationError,
   apiKeyCreateSchema: () => apiKeyCreateSchema,
   contextRequestSchema: () => contextRequestSchema,
@@ -230,6 +231,12 @@ var ValidationError = class extends ApiError {
     this.details = details;
   }
 };
+var UpstreamInterceptError = class extends ApiError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response, "NEXUS_UPSTREAM_INTERCEPT");
+    this.name = "UpstreamInterceptError";
+  }
+};
 var NotFoundError = class extends ApiError {
   constructor(message, response) {
     super(message, 404, response, "NEXUS_NOT_FOUND_ERROR");
@@ -641,6 +648,35 @@ var OfflineQueue = class {
 };
 
 // src/http/client.ts
+function redirectHost(location) {
+  if (typeof location !== "string" || location === "") return "an unknown host";
+  try {
+    return new URL(location).host;
+  } catch {
+    return "an unparseable location";
+  }
+}
+function upstreamRedirectError(response, url) {
+  const headers = response.headers ?? {};
+  const host = redirectHost(headers.location ?? headers.Location);
+  return new UpstreamInterceptError(
+    `Request to ${url ?? "the API"} was redirected (HTTP ${response.status}) to ${host} instead of being answered by Nexus. This is typically an expired or missing edge credential (e.g. a Cloudflare Access service token) \u2014 the API itself was never reached.`,
+    response.status,
+    response.data
+  );
+}
+function assertNotIntercepted(response) {
+  if (response.config?.responseType === "text") return;
+  const headers = response.headers ?? {};
+  const raw = headers["content-type"] ?? headers["Content-Type"];
+  if (typeof raw !== "string" || raw === "") return;
+  if (raw.toLowerCase().includes("json")) return;
+  throw new UpstreamInterceptError(
+    `Request to ${response.config?.url ?? "the API"} returned HTTP ${response.status} with content-type "${raw}" where JSON was expected. Something between this client and Nexus answered the request (auth edge, proxy, or captive portal); treating it as data would look like an empty result.`,
+    response.status,
+    response.data
+  );
+}
 var HttpClient = class {
   /**
    * Create a new HTTP client.
@@ -658,7 +694,14 @@ var HttpClient = class {
     }
     this.axios = import_axios.default.create({
       baseURL: config.baseUrl,
-      timeout: config.timeout
+      timeout: config.timeout,
+      // Never follow redirects (Kairos#66 / Aether#372). An auth edge such as
+      // Cloudflare Access answers an unauthenticated call with 302 → its own
+      // login page; following it yields a 200 with HTML, which is
+      // indistinguishable from an empty result to the caller. With
+      // maxRedirects: 0 the 3xx fails axios' status validation and reaches the
+      // error interceptor, which turns it into an UpstreamInterceptError.
+      maxRedirects: 0
     });
     this.setupRequestInterceptor();
     this.setupResponseInterceptor();
@@ -873,8 +916,11 @@ var HttpClient = class {
    */
   setupResponseInterceptor() {
     this.axios.interceptors.response.use(
-      // Success handler -- pass through
-      (response) => response,
+      // Success handler -- pass through, except for a 2xx that is not JSON.
+      (response) => {
+        assertNotIntercepted(response);
+        return response;
+      },
       // Error handler -- normalise into NexusError hierarchy
       (error) => {
         if (import_axios.default.isCancel(error)) {
@@ -888,6 +934,11 @@ var HttpClient = class {
             )
           );
         }
+        if (error.response && error.response.status >= 300 && error.response.status < 400) {
+          return Promise.reject(
+            upstreamRedirectError(error.response, error.config?.url)
+          );
+        }
         if (error.response) {
           const apiError = ApiError.fromResponse(error.response);
           const reqUrl = error.config?.url ?? "";
@@ -1544,6 +1595,7 @@ var apiKeyCreateSchema = import_zod5.z.object({
   RateLimitError,
   TenantService,
   TimeoutError,
+  UpstreamInterceptError,
   ValidationError,
   apiKeyCreateSchema,
   contextRequestSchema,