@nexusm/sdk 4.0.0 → 5.1.0

package/dist/index.d.mts

@@ -457,6 +457,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.
      *
@@ -939,22 +954,25 @@ interface MemorySearchResult {
 /**
  * Paginated list of memories.
  *
- * GET /memories?user_id=...
+ * GET /memories?user_id=... — mirrors backend `MemoryListResponse` (FLAT
+ * container).
+ *
+ * v5.0.0 BREAKING: was nested `{data, pagination:{total, limit, offset,
+ * has_more}}` — that shape never existed on the wire. The backend response
+ * is flat `{memories, total_count, limit, offset, has_next}`; the old nested
+ * shape meant `result.data` was always `undefined` at runtime.
  */
 interface MemoryList {
     /** Array of memory records */
-    data: Memory[];
-    /** Pagination metadata */
-    pagination: {
-        /** Total number of memories */
-        total: number;
-        /** Current page size limit */
-        limit: number;
-        /** Current offset */
-        offset: number;
-        /** Whether more results exist */
-        has_more: boolean;
-    };
+    memories: Memory[];
+    /** Total number of memories matching the query */
+    total_count: number;
+    /** Current page size limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more results exist beyond this page */
+    has_next: boolean;
 }
 /**
  * A single journal entry representing a memory on a specific date.
@@ -1004,8 +1022,13 @@ interface JournalResponse {
  * Parameters for listing memories with optional filtering and pagination.
  */
 interface MemoryListParams {
-    /** Filter memories by user ID */
-    user_id?: string;
+    /**
+     * User ID within the tenant whose memories to list.
+     *
+     * v5.0.0 BREAKING: now required — backend `GET /memories` declares
+     * `user_id` as `Query(..., min_length=1)`; omitting it returns 422.
+     */
+    user_id: string;
     /** Filter by memory type classification */
     memory_type?: MemoryType;
     /** Maximum number of results per page */
@@ -1027,8 +1050,9 @@ interface MemoryJournalParams {
     user_id?: string;
 }
 /**
- * Service for managing long-term memories via Mem0.
+ * Service for managing long-term memories.
  *
+ * Backed by the Nexus Memory Service (Native pgvector + ProfileWorker).
  * Provides full CRUD operations, semantic search, and the chronological
  * Memory Journal view for reviewing memories over time.
  *
@@ -1151,16 +1175,22 @@ interface Conversation {
     tenant_id: string;
     /** User ID that owns this conversation */
     user_id: string;
-    /** Originating agent (null when not agent-created) */
-    agent_id?: string | null;
+    /**
+     * Originating agent (null when not agent-created).
+     *
+     * v5.0.0: required-nullable convention — always emitted by the backend
+     * (`ConversationResponse.agent_id: str | None`), value may be null. Was
+     * `agent_id?: string | null` (optional); now `string | null` (required dict).
+     */
+    agent_id: string | null;
     /** Conversation status (e.g. active / archived) */
     status: string;
-    /** Auto-generated conversation summary */
-    summary?: string | null;
+    /** Auto-generated conversation summary (null until first summary worker run) */
+    summary: string | null;
     /** Total number of messages in the conversation */
     message_count: number;
-    /** Additional metadata key-value pairs */
-    metadata?: Record<string, unknown>;
+    /** Additional metadata key-value pairs (always emitted, defaults to {}) */
+    metadata: Record<string, unknown>;
     /** Timestamp when the conversation was created (ISO 8601) */
     created_at: string;
     /** Timestamp when the conversation was last updated (ISO 8601) */
@@ -1169,13 +1199,20 @@ interface Conversation {
 /**
  * Request payload for creating a new conversation.
  *
- * POST /conversations
+ * POST /conversations — mirrors backend `CreateConversationRequest`.
+ *
+ * v5.0.0 BREAKING: removed phantom `session_id` — the backend
+ * (`CreateConversationRequest`) does not accept it; it was silently dropped
+ * by Pydantic `extra=ignore`, and the session id is ALWAYS auto-generated
+ * server-side regardless of input (the old "auto-generated if not provided"
+ * doc was false). Added `agent_id` — the backend accepts it but the SDK had
+ * no way to send it.
  */
 interface ConversationCreate {
     /** User ID to associate the conversation with */
     user_id: string;
-    /** Custom session ID (auto-generated if not provided) */
-    session_id?: string;
+    /** Optional agent identifier to associate the conversation with */
+    agent_id?: string;
     /** Additional metadata key-value pairs */
     metadata?: Record<string, unknown>;
 }
@@ -1295,19 +1332,26 @@ interface ConversationSummary {
  * @module services/conversations
  * @description Conversation Service - Conversation history and auto-summary management.
  *
- * Wraps the Nexus Conversation API powered by Zep OSS. Supports
- * conversation lifecycle management, message operations, and
- * auto-generated summaries via temporal graph analysis.
+ * Wraps the Nexus Conversation API (Native implementation: incremental
+ * summaries produced by the backend SummaryWorker, NOT Zep OSS). Supports
+ * conversation lifecycle management, message operations, and access to
+ * auto-generated summaries.
  *
- * Based on Nexus API v2.0 - /conversations endpoints
+ * v5.0.0: corrected stale "Zep OSS"/"temporal graph"/"API v2.0" docs — the
+ * backend has always used a Native SummaryWorker.
  */
 
 /**
  * Parameters for listing conversations with optional filtering and pagination.
  */
 interface ConversationListParams {
-    /** Filter conversations by user ID */
-    user_id?: string;
+    /**
+     * User ID within the tenant whose conversations to list.
+     *
+     * v5.0.0 BREAKING: now required — backend `GET /conversations` declares
+     * `user_id` as `Query(..., min_length=1)`; omitting it returns 422.
+     */
+    user_id: string;
     /** Maximum number of results per page */
     limit?: number;
     /** Offset for pagination */
@@ -1323,11 +1367,11 @@ interface MessageListParams {
     offset?: number;
 }
 /**
- * Service for managing conversations and messages via Zep OSS.
+ * Service for managing conversations and messages.
  *
  * Provides conversation lifecycle management (create, list, get, delete),
  * message operations (add, list), and access to auto-generated summaries
- * produced by Zep's temporal graph analysis.
+ * produced by the backend SummaryWorker (Native, incremental).
  *
  * @example
  * ```typescript
@@ -1379,11 +1423,11 @@ declare class ConversationService extends BaseService {
     /**
      * 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.
+     * The message is appended to the conversation's message sequence. The
+     * backend SummaryWorker asynchronously updates the conversation summary
+     * after new messages are added.
      *
-     * @param conversationId - UUID of the target conversation.
+     * @param conversationId - Compound conversation ID ("tenant::user::session").
      * @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.
@@ -1394,7 +1438,7 @@ declare class ConversationService extends BaseService {
      *
      * Messages are returned in chronological order (oldest first).
      *
-     * @param conversationId - UUID of the conversation.
+     * @param conversationId - Compound conversation ID ("tenant::user::session").
      * @param params - Optional pagination controls (limit, offset).
      * @returns Paginated list of messages.
      * @throws {ApiError} 404 if the conversation does not exist.
@@ -1403,21 +1447,24 @@ declare class ConversationService extends BaseService {
     /**
      * 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.
+     * Summaries are produced incrementally by the backend SummaryWorker from
+     * the conversation history.
      *
-     * @param conversationId - UUID of the conversation.
-     * @returns The conversation summary with key points and generation timestamp.
+     * @param conversationId - Compound conversation ID ("tenant::user::session").
+     * @returns The conversation summary ({@link ConversationSummary}: summary
+     *   text + message counts + created_at). Note: no "key points" or
+     *   "generated_at" fields — those were phantom (removed in v4.0.0).
      * @throws {ApiError} 404 if the conversation does not exist.
      */
     getSummary(conversationId: string, options?: RequestOptions): Promise<ConversationSummary>;
     /**
-     * Delete a conversation and all its messages.
+     * Delete a conversation.
      *
-     * This operation is irreversible. The conversation, all associated
-     * messages, and the generated summary will be permanently removed.
+     * Soft-delete: the backend sets `deleted_at` (the conversation stops
+     * appearing in list/get) rather than physically removing the row and its
+     * messages.
      *
-     * @param conversationId - UUID of the conversation to delete.
+     * @param conversationId - Compound conversation ID ("tenant::user::session").
      * @throws {ApiError} 404 if the conversation does not exist.
      */
     delete(conversationId: string, options?: RequestOptions): Promise<void>;
@@ -1903,9 +1950,12 @@ interface ApiKeyCreate {
     /** Human-readable name for the API key (1-255 characters) */
     name: string;
     /**
-     * Permission scopes for the key (known values: read, write, admin, "*").
-     * @default ["*"] — the backend default grants the full wildcard; tightening
-     * the default is a separate backend security follow-up.
+     * Permission scopes for the key (known values: read, write, admin,
+     * admin:dashboard, feedback:diagnose, "*" wildcard).
+     * @default ["read", "write"] — least-privilege default (backend tightened
+     * in security-scopes-admin-hardening, 2026-06-11). The "*" wildcard must be
+     * requested explicitly; the default intentionally omits admin:dashboard /
+     * feedback:diagnose.
      */
     scopes?: string[];
     /**
@@ -2270,6 +2320,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.
@@ -2321,6 +2498,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;
     /**
@@ -2575,16 +2754,16 @@ declare const memorySearchSchema: z.ZodObject<{
 
 declare const conversationCreateSchema: z.ZodObject<{
     user_id: z.ZodString;
-    session_id: z.ZodOptional<z.ZodString>;
+    agent_id: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     user_id: string;
     metadata?: Record<string, unknown> | undefined;
-    session_id?: string | undefined;
+    agent_id?: string | undefined;
 }, {
     user_id: string;
     metadata?: Record<string, unknown> | undefined;
-    session_id?: string | undefined;
+    agent_id?: string | undefined;
 }>;
 declare const messageCreateSchema: z.ZodObject<{
     role: z.ZodEnum<["user", "assistant", "system", "tool"]>;