@nexusm/sdk 4.0.0 → 5.0.0

package/dist/index.d.mts

@@ -939,22 +939,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 +1007,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 +1035,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 +1160,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 +1184,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 +1317,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 +1352,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 +1408,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 +1423,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 +1432,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 +1935,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[];
     /**
@@ -2575,16 +2610,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"]>;

package/dist/index.d.ts

@@ -939,22 +939,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 +1007,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 +1035,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 +1160,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 +1184,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 +1317,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 +1352,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 +1408,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 +1423,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 +1432,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 +1935,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[];
     /**
@@ -2575,16 +2610,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"]>;

package/dist/index.js

@@ -1089,7 +1089,7 @@ var import_zod3 = require("zod");
 var messageRoleSchema = import_zod3.z.enum(["user", "assistant", "system", "tool"]);
 var conversationCreateSchema = import_zod3.z.object({
   user_id: import_zod3.z.string().min(1),
-  session_id: import_zod3.z.string().optional(),
+  agent_id: import_zod3.z.string().max(255).optional(),
   metadata: import_zod3.z.record(import_zod3.z.unknown()).optional()
 });
 var messageCreateSchema = import_zod3.z.object({
@@ -1139,11 +1139,11 @@ var ConversationService = class 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.
@@ -1160,7 +1160,7 @@ var ConversationService = class 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.
@@ -1175,23 +1175,26 @@ var ConversationService = class 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.
    */
   async getSummary(conversationId, options) {
     return this.http.get(`/conversations/${conversationId}/summary`, void 0, options?.signal);
   }
   /**
-   * 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.
    */
   async delete(conversationId, options) {