@nexusm/sdk 5.0.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;
@@ -457,6 +438,21 @@ declare class HttpClient {
      * @returns The parsed response body.
      */
     patch<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a GET request and return the raw response body as a string.
+     *
+     * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+     * return `text/csv` or `application/json` as a raw file stream rather than a
+     * JSON-parsed object.  The retry and auth interceptors still apply; the
+     * response cache is intentionally bypassed (export payloads are not cacheable
+     * at the SDK layer).
+     *
+     * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+     * @param params - Optional query parameters.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The raw response body as a string.
+     */
+    getText(path: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
     /**
      * Send a DELETE request.
      *
@@ -2305,6 +2301,133 @@ declare class ErrorService extends BaseService {
     submit(data: ErrorReportRequest, options?: RequestOptions): Promise<ErrorReportResponse>;
 }
 
+/**
+ * @module types/dashboard
+ * @description Dashboard Service type definitions.
+ *
+ * Mirrors the Nexus API dashboard export contract:
+ * - GET /v1/dashboard/export — download a dataset as CSV or JSON
+ *
+ * The export endpoint returns raw file content (text/csv or application/json),
+ * not a JSON-parsed object.  The SDK therefore exposes these types only for
+ * the _request_ side; the return value is `string`.
+ */
+/**
+ * The set of exportable dashboard datasets.
+ *
+ * Must stay in sync with the backend `DashboardExportDataset` Literal:
+ * - `quality_distribution` — Quality score bucket distribution
+ * - `feedback_trend`       — Feedback rating trend over time
+ * - `diagnosis_stats`      — Diagnosis type statistics
+ * - `feedback_health`      — Overall feedback health metrics
+ * - `error_heatmap`        — Error frequency heatmap by endpoint / time
+ * - `ab_distribution`      — A/B experiment assignment distribution
+ */
+type DashboardExportDataset = 'quality_distribution' | 'feedback_trend' | 'diagnosis_stats' | 'feedback_health' | 'error_heatmap' | 'ab_distribution';
+/**
+ * Query parameters for `GET /v1/dashboard/export`.
+ */
+interface DashboardExportParams {
+    /**
+     * The dataset to export.  Required.
+     *
+     * Must be one of the six whitelisted values ({@link DashboardExportDataset}).
+     * The backend returns HTTP 422 for unknown values.
+     */
+    dataset: DashboardExportDataset;
+    /**
+     * File format for the exported data.
+     *
+     * - `'csv'`  — Comma-separated values (default when omitted).
+     * - `'json'` — Raw JSON text (not parsed; returned as a string by the SDK).
+     *
+     * @default 'csv'
+     */
+    format?: 'csv' | 'json';
+    /**
+     * Filter results to a specific tenant.
+     *
+     * Only usable by API keys that carry the admin scope.  The backend returns
+     * HTTP 403 when this field is present but the caller lacks admin privileges,
+     * and HTTP 400 when the value is not a valid UUID (it is normalized to
+     * canonical form server-side).
+     */
+    target_tenant_id?: string;
+}
+
+/**
+ * @module services/dashboard
+ * @description Dashboard Service — export analytics datasets.
+ *
+ * Wraps the Nexus Dashboard API:
+ * - GET /v1/dashboard/export — download a dataset as raw CSV or JSON text
+ *
+ * The export endpoint is a file-download endpoint: the backend responds with
+ * `Content-Disposition: attachment` and a raw file body (not a JSON envelope).
+ * Accordingly, `export()` returns the raw response string rather than parsing
+ * it into an object — callers receive exactly the bytes the server sent.
+ *
+ * ### WebSocket realtime subscriptions — deferred
+ *
+ * US-033b FU-3 scope is limited to the REST export method.  A WebSocket
+ * subscription helper (`subscribe()` / `DashboardSubscription`) was evaluated
+ * for inclusion but is deferred to FU-4 (WS replay/catchup protocol decision).
+ * Reasons:
+ *   1. The WS message schema is not yet stabilised (FU-4 owns that contract).
+ *   2. A proper WS abstraction requires a browser/Node `WebSocket` shim strategy
+ *      that is a non-trivial independent surface.
+ * Track the WS helper in FU-4; this file should be extended there.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Download quality distribution as CSV (default format)
+ * const csv = await nexus.dashboard.export({ dataset: 'quality_distribution' });
+ * // csv is a string like: "bucket,count\n0-1,12\n1-2,45\n..."
+ *
+ * // Download feedback trend as JSON
+ * const json = await nexus.dashboard.export({
+ *   dataset: 'feedback_trend',
+ *   format: 'json',
+ * });
+ *
+ * // Admin: export data scoped to a specific tenant
+ * const tenantCsv = await nexus.dashboard.export({
+ *   dataset: 'error_heatmap',
+ *   format: 'csv',
+ *   target_tenant_id: 'tenant-abc',
+ * });
+ * ```
+ */
+
+/**
+ * Service for exporting dashboard analytics datasets.
+ *
+ * Exposes `GET /v1/dashboard/export` as a typed method that returns the raw
+ * file body (CSV or JSON text) as a string.
+ */
+declare class DashboardService extends BaseService {
+    /**
+     * Export a dashboard dataset as raw file content.
+     *
+     * Sends `GET /dashboard/export` with the given query parameters and returns
+     * the raw response body as a string.  The string is exactly the file the
+     * server would send for a browser download:
+     * - `format: 'csv'` (default) → comma-separated text
+     * - `format: 'json'`          → JSON text (not parsed into an object)
+     *
+     * @param params  - Dataset selection and format options.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns Raw file body string.
+     *
+     * @throws {ApiError} HTTP 401 — missing or invalid API key.
+     * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+     * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+     */
+    export(params: DashboardExportParams, options?: RequestOptions): Promise<string>;
+}
+
 /**
  * @module client
  * @description Main entry point for the Nexus SDK.
@@ -2356,6 +2479,8 @@ declare class NexusClient {
     readonly feedback: FeedbackService;
     /** Error reporting — submit structured error reports (US-031). */
     readonly errors: ErrorService;
+    /** Dashboard analytics — export datasets as CSV or JSON (US-033b FU-3). */
+    readonly dashboard: DashboardService;
     /** @internal Shared HTTP transport. */
     private readonly http;
     /**
@@ -2505,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);
 }
@@ -2676,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;
@@ -457,6 +438,21 @@ declare class HttpClient {
      * @returns The parsed response body.
      */
     patch<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a GET request and return the raw response body as a string.
+     *
+     * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+     * return `text/csv` or `application/json` as a raw file stream rather than a
+     * JSON-parsed object.  The retry and auth interceptors still apply; the
+     * response cache is intentionally bypassed (export payloads are not cacheable
+     * at the SDK layer).
+     *
+     * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+     * @param params - Optional query parameters.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The raw response body as a string.
+     */
+    getText(path: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
     /**
      * Send a DELETE request.
      *
@@ -2305,6 +2301,133 @@ declare class ErrorService extends BaseService {
     submit(data: ErrorReportRequest, options?: RequestOptions): Promise<ErrorReportResponse>;
 }
 
+/**
+ * @module types/dashboard
+ * @description Dashboard Service type definitions.
+ *
+ * Mirrors the Nexus API dashboard export contract:
+ * - GET /v1/dashboard/export — download a dataset as CSV or JSON
+ *
+ * The export endpoint returns raw file content (text/csv or application/json),
+ * not a JSON-parsed object.  The SDK therefore exposes these types only for
+ * the _request_ side; the return value is `string`.
+ */
+/**
+ * The set of exportable dashboard datasets.
+ *
+ * Must stay in sync with the backend `DashboardExportDataset` Literal:
+ * - `quality_distribution` — Quality score bucket distribution
+ * - `feedback_trend`       — Feedback rating trend over time
+ * - `diagnosis_stats`      — Diagnosis type statistics
+ * - `feedback_health`      — Overall feedback health metrics
+ * - `error_heatmap`        — Error frequency heatmap by endpoint / time
+ * - `ab_distribution`      — A/B experiment assignment distribution
+ */
+type DashboardExportDataset = 'quality_distribution' | 'feedback_trend' | 'diagnosis_stats' | 'feedback_health' | 'error_heatmap' | 'ab_distribution';
+/**
+ * Query parameters for `GET /v1/dashboard/export`.
+ */
+interface DashboardExportParams {
+    /**
+     * The dataset to export.  Required.
+     *
+     * Must be one of the six whitelisted values ({@link DashboardExportDataset}).
+     * The backend returns HTTP 422 for unknown values.
+     */
+    dataset: DashboardExportDataset;
+    /**
+     * File format for the exported data.
+     *
+     * - `'csv'`  — Comma-separated values (default when omitted).
+     * - `'json'` — Raw JSON text (not parsed; returned as a string by the SDK).
+     *
+     * @default 'csv'
+     */
+    format?: 'csv' | 'json';
+    /**
+     * Filter results to a specific tenant.
+     *
+     * Only usable by API keys that carry the admin scope.  The backend returns
+     * HTTP 403 when this field is present but the caller lacks admin privileges,
+     * and HTTP 400 when the value is not a valid UUID (it is normalized to
+     * canonical form server-side).
+     */
+    target_tenant_id?: string;
+}
+
+/**
+ * @module services/dashboard
+ * @description Dashboard Service — export analytics datasets.
+ *
+ * Wraps the Nexus Dashboard API:
+ * - GET /v1/dashboard/export — download a dataset as raw CSV or JSON text
+ *
+ * The export endpoint is a file-download endpoint: the backend responds with
+ * `Content-Disposition: attachment` and a raw file body (not a JSON envelope).
+ * Accordingly, `export()` returns the raw response string rather than parsing
+ * it into an object — callers receive exactly the bytes the server sent.
+ *
+ * ### WebSocket realtime subscriptions — deferred
+ *
+ * US-033b FU-3 scope is limited to the REST export method.  A WebSocket
+ * subscription helper (`subscribe()` / `DashboardSubscription`) was evaluated
+ * for inclusion but is deferred to FU-4 (WS replay/catchup protocol decision).
+ * Reasons:
+ *   1. The WS message schema is not yet stabilised (FU-4 owns that contract).
+ *   2. A proper WS abstraction requires a browser/Node `WebSocket` shim strategy
+ *      that is a non-trivial independent surface.
+ * Track the WS helper in FU-4; this file should be extended there.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Download quality distribution as CSV (default format)
+ * const csv = await nexus.dashboard.export({ dataset: 'quality_distribution' });
+ * // csv is a string like: "bucket,count\n0-1,12\n1-2,45\n..."
+ *
+ * // Download feedback trend as JSON
+ * const json = await nexus.dashboard.export({
+ *   dataset: 'feedback_trend',
+ *   format: 'json',
+ * });
+ *
+ * // Admin: export data scoped to a specific tenant
+ * const tenantCsv = await nexus.dashboard.export({
+ *   dataset: 'error_heatmap',
+ *   format: 'csv',
+ *   target_tenant_id: 'tenant-abc',
+ * });
+ * ```
+ */
+
+/**
+ * Service for exporting dashboard analytics datasets.
+ *
+ * Exposes `GET /v1/dashboard/export` as a typed method that returns the raw
+ * file body (CSV or JSON text) as a string.
+ */
+declare class DashboardService extends BaseService {
+    /**
+     * Export a dashboard dataset as raw file content.
+     *
+     * Sends `GET /dashboard/export` with the given query parameters and returns
+     * the raw response body as a string.  The string is exactly the file the
+     * server would send for a browser download:
+     * - `format: 'csv'` (default) → comma-separated text
+     * - `format: 'json'`          → JSON text (not parsed into an object)
+     *
+     * @param params  - Dataset selection and format options.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns Raw file body string.
+     *
+     * @throws {ApiError} HTTP 401 — missing or invalid API key.
+     * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+     * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+     */
+    export(params: DashboardExportParams, options?: RequestOptions): Promise<string>;
+}
+
 /**
  * @module client
  * @description Main entry point for the Nexus SDK.
@@ -2356,6 +2479,8 @@ declare class NexusClient {
     readonly feedback: FeedbackService;
     /** Error reporting — submit structured error reports (US-031). */
     readonly errors: ErrorService;
+    /** Dashboard analytics — export datasets as CSV or JSON (US-033b FU-3). */
+    readonly dashboard: DashboardService;
     /** @internal Shared HTTP transport. */
     private readonly http;
     /**
@@ -2505,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);
 }
@@ -2676,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();
@@ -794,6 +837,30 @@ var HttpClient = class {
     this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
     return result;
   }
+  /**
+   * Send a GET request and return the raw response body as a string.
+   *
+   * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+   * return `text/csv` or `application/json` as a raw file stream rather than a
+   * JSON-parsed object.  The retry and auth interceptors still apply; the
+   * response cache is intentionally bypassed (export payloads are not cacheable
+   * at the SDK layer).
+   *
+   * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+   * @param params - Optional query parameters.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The raw response body as a string.
+   */
+  async getText(path, params, signal) {
+    return this.retry.execute(async () => {
+      const response = await this.axios.get(path, {
+        params,
+        signal,
+        responseType: "text"
+      });
+      return response.data;
+    });
+  }
   /**
    * Send a DELETE request.
    *
@@ -849,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)) {
@@ -864,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 ?? "";
@@ -1410,6 +1485,35 @@ var ErrorService = class extends BaseService {
   }
 };
 
+// src/services/dashboard.ts
+var DashboardService = class extends BaseService {
+  /**
+   * Export a dashboard dataset as raw file content.
+   *
+   * Sends `GET /dashboard/export` with the given query parameters and returns
+   * the raw response body as a string.  The string is exactly the file the
+   * server would send for a browser download:
+   * - `format: 'csv'` (default) → comma-separated text
+   * - `format: 'json'`          → JSON text (not parsed into an object)
+   *
+   * @param params  - Dataset selection and format options.
+   * @param options - Optional request options (e.g. AbortSignal).
+   * @returns Raw file body string.
+   *
+   * @throws {ApiError} HTTP 401 — missing or invalid API key.
+   * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+   * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+   */
+  async export(params, options) {
+    const query = { dataset: params.dataset };
+    if (params.format !== void 0) query["format"] = params.format;
+    if (params.target_tenant_id !== void 0) {
+      query["target_tenant_id"] = params.target_tenant_id;
+    }
+    return this.http.getText("/dashboard/export", query, options?.signal);
+  }
+};
+
 // src/client.ts
 var NexusClient = class {
   /**
@@ -1431,6 +1535,7 @@ var NexusClient = class {
     this.tenants = new TenantService(this.http);
     this.feedback = new FeedbackService(this.http);
     this.errors = new ErrorService(this.http);
+    this.dashboard = new DashboardService(this.http);
     if (resolved.autoErrorReport) {
       this.http.onApiError = (statusCode, method, url, detail) => {
         this.errors.submit({
@@ -1490,6 +1595,7 @@ var apiKeyCreateSchema = import_zod5.z.object({
   RateLimitError,
   TenantService,
   TimeoutError,
+  UpstreamInterceptError,
   ValidationError,
   apiKeyCreateSchema,
   contextRequestSchema,