@nexusm/sdk 2.0.0 → 3.0.0

package/dist/index.d.mts

@@ -1504,26 +1504,15 @@ interface GraphQueryResponse {
  */
 
 /**
- * Request payload for creating a new knowledge entity.
+ * Parameters for listing knowledge entities.
  *
- * POST /knowledge/entities
- */
-interface EntityCreate {
-    /** Entity display name */
-    name: string;
-    /** Entity type classification (e.g., Person, Organization, Concept) */
-    entity_type: string;
-    /** Entity description */
-    description?: string;
-    /** Additional entity properties */
-    properties?: Record<string, unknown>;
-}
-/**
- * Parameters for listing knowledge entities with optional filtering.
+ * v3.0.0 BREAKING: `user_id` is required — the backend (and OpenAPI) demand
+ * it (`Query(..., min_length=1)`); the previous optional typing let calls
+ * compile that 422'd at runtime.
  */
 interface EntityListParams {
-    /** Filter entities by user ID (owner) */
-    user_id?: string;
+    /** Entity owner user ID (required by the backend) */
+    user_id: string;
     /** Filter by entity type classification */
     entity_type?: string;
     /** Maximum number of results to return */
@@ -1534,9 +1523,11 @@ interface EntityListParams {
 /**
  * Service for managing the knowledge graph via Fast GraphRAG.
  *
- * Provides entity CRUD, BFS graph traversal queries, and automatic
+ * Provides entity listing, BFS graph traversal queries, and automatic
  * entity/relationship extraction from unstructured text. Supports
  * both public (agent-owned) and private (user-owned) knowledge.
+ * (v3.0.0: entity creation was removed — the backend has no
+ * POST /knowledge/entities route; entities are created via extract().)
  *
  * @example
  * ```typescript
@@ -1559,19 +1550,12 @@ interface EntityListParams {
  */
 declare class KnowledgeService extends BaseService {
     /**
-     * Create a new knowledge entity in the graph.
+     * List knowledge entities for a user with optional filtering.
      *
-     * @param data - Entity creation payload including name, type, and optional description/properties.
-     * @returns The newly created entity with generated entity_id.
-     */
-    createEntity(data: EntityCreate, options?: RequestOptions): Promise<KnowledgeEntity>;
-    /**
-     * List knowledge entities with optional filtering.
-     *
-     * @param params - Optional filters for user_id, entity_type, and pagination controls.
+     * @param params - Filters: required user_id (backend-enforced), optional entity_type and pagination controls.
      * @returns Paginated list of knowledge entities.
      */
-    listEntities(params?: EntityListParams, options?: RequestOptions): Promise<EntityListResponse>;
+    listEntities(params: EntityListParams, options?: RequestOptions): Promise<EntityListResponse>;
     /**
      * Query the knowledge graph using BFS traversal.
      *
@@ -1753,14 +1737,21 @@ declare class ActivityService extends BaseService {
  * Supports multi-tenant isolation, API key management,
  * quota tracking, and usage statistics.
  *
- * Based on Nexus API v2.0 OpenAPI specification.
+ * v3.0.0 BREAKING (tenant-contract-reconciliation, 2026-06-10): canonical =
+ * backend Pydantic response models (`schemas/tenant.py`). The previous shapes
+ * were drifted: `Tenant` had a phantom nested `usage` object (the wire is
+ * flat), `UsageStats` declared 3 phantom fields and missed 11 real ones, and
+ * `ApiKeyCreate` used the phantom request field `expires_days` (the wire is
+ * `expires_in_days` — the old name was silently dropped by the backend,
+ * creating never-expiring keys).
  */
 /** Available tenant subscription tiers */
 type TenantTier = 'free' | 'starter' | 'pro' | 'enterprise';
-/** API Key permission scopes */
-type ApiKeyScope = 'read' | 'write' | 'admin';
 /**
  * Tenant quotas configuration defining resource limits.
+ *
+ * The backend serializes a free-form object; the keys below are the
+ * well-known ones. Unknown keys are preserved via the index signature.
  */
 interface TenantQuotas {
     /** Maximum number of memories allowed */
@@ -1769,23 +1760,18 @@ interface TenantQuotas {
     max_conversations?: number;
     /** Maximum API calls per day */
     max_api_calls_per_day?: number;
-}
-/**
- * Current resource usage counts for a tenant.
- */
-interface TenantUsage {
-    /** Current number of memories stored */
-    memories_count?: number;
-    /** Current number of conversations */
-    conversations_count?: number;
-    /** API calls made today */
-    api_calls_today?: number;
+    /** Forward-compatible: any additional quota dimensions */
+    [key: string]: unknown;
 }
 /**
  * A tenant (organization) on the Nexus platform.
  * Each tenant has isolated data and configurable quotas.
  *
- * GET /tenants/me
+ * GET /tenants/me — mirrors backend `TenantInfoResponse` (flat shape).
+ *
+ * v3.0.0 BREAKING: usage counts are FLAT top-level fields (the nested
+ * `usage` object never existed on the wire); adds `quota_remaining` and
+ * `graph_nodes_count` (previously missing).
  */
 interface Tenant {
     /** Unique tenant identifier (UUID) */
@@ -1795,17 +1781,28 @@ interface Tenant {
     /** Subscription tier */
     tier: TenantTier;
     /** Resource quotas */
-    quotas?: TenantQuotas;
-    /** Current resource usage */
-    usage?: TenantUsage;
+    quotas: TenantQuotas;
+    /** Remaining headroom per quota dimension */
+    quota_remaining: Record<string, number>;
     /** Timestamp when the tenant was created (ISO 8601) */
     created_at: string;
+    /** Current number of memories stored (flat — not nested under `usage`) */
+    memories_count: number;
+    /** Current number of conversations (flat — not nested under `usage`) */
+    conversations_count: number;
+    /** Current number of knowledge graph nodes */
+    graph_nodes_count: number;
 }
 /**
  * An API key for authenticating with the Nexus platform.
  * The full key value is only returned once at creation time.
  *
  * GET /tenants/me/api-keys
+ *
+ * v3.0.0: `scopes` is a free-form string array documenting backend reality —
+ * known values are `"read"`, `"write"`, `"admin"` and the `"*"` wildcard
+ * (the backend authorizes via `scope in scopes or "*" in scopes`). The old
+ * `ApiKeyScope` enum could not represent `"*"`, the actual default.
  */
 interface ApiKey {
     /** Unique API key identifier (UUID) */
@@ -1814,8 +1811,8 @@ interface ApiKey {
     key_prefix: string;
     /** Human-readable name for the API key */
     name: string;
-    /** Permission scopes granted to this key */
-    scopes: ApiKeyScope[];
+    /** Permission scopes granted to this key (known values: read, write, admin, "*") */
+    scopes: string[];
     /** Expiration timestamp (null = never expires) (ISO 8601) */
     expires_at?: string | null;
     /** Last time this key was used (ISO 8601) */
@@ -1826,23 +1823,28 @@ interface ApiKey {
 /**
  * Request payload for creating a new API key.
  *
- * POST /tenants/me/api-keys
+ * POST /tenants/me/api-keys — mirrors backend `ApiKeyCreate`.
+ *
+ * v3.0.0 BREAKING: `expires_days` → `expires_in_days` (the backend request
+ * field). The old name was silently ignored by the backend (no
+ * `extra=forbid`), so keys created through the SDK never expired.
  */
 interface ApiKeyCreate {
-    /** Human-readable name for the API key (1-100 characters) */
+    /** Human-readable name for the API key (1-255 characters) */
     name: string;
     /**
-     * Permission scopes for the key.
-     * @default ["read", "write"]
+     * 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.
      */
-    scopes?: ApiKeyScope[];
+    scopes?: string[];
     /**
      * Number of days until the key expires.
      * Omit for a key that never expires.
      * @minimum 1
      * @maximum 365
      */
-    expires_days?: number;
+    expires_in_days?: number;
 }
 /**
  * Response from creating a new API key.
@@ -1859,19 +1861,40 @@ interface ApiKeyCreated extends ApiKey {
 /**
  * Usage statistics for a tenant over a specific time period.
  *
- * GET /tenants/me/usage
+ * GET /tenants/me/usage — mirrors backend `UsageStatsResponse` (13 fields).
+ *
+ * v3.0.0 BREAKING: full realignment. The previous 5-field shape declared 3
+ * phantom fields (`tokens_used` / `memories_created` / `conversations_created`)
+ * and missed the latency/success-rate/storage fields the backend actually
+ * emits.
  */
 interface UsageStats {
+    /** Tenant identifier (UUID) */
+    tenant_id: string;
     /** Time period for the statistics */
     period: 'day' | 'week' | 'month';
     /** Total API calls in the period */
     api_calls: number;
-    /** Total tokens consumed */
-    tokens_used?: number;
-    /** Number of memories created in the period */
-    memories_created?: number;
-    /** Number of conversations created in the period */
-    conversations_created?: number;
+    /** Success rate over the period (0-100) */
+    success_rate: number;
+    /** Average request latency in milliseconds */
+    avg_latency_ms: number;
+    /** p50 latency in milliseconds (null when no traffic) */
+    p50_latency_ms?: number | null;
+    /** p95 latency in milliseconds (null when no traffic) */
+    p95_latency_ms?: number | null;
+    /** p99 latency in milliseconds (null when no traffic) */
+    p99_latency_ms?: number | null;
+    /** Current number of memories stored */
+    memories_count: number;
+    /** Current number of conversations */
+    conversations_count: number;
+    /** Current number of knowledge graph nodes */
+    graph_nodes_count: number;
+    /** Storage consumed in bytes */
+    storage_used_bytes: number;
+    /** Storage limit in bytes */
+    storage_limit_bytes: number;
 }
 
 /**
@@ -1900,9 +1923,9 @@ interface UsageStats {
  * const tenant = await nexus.tenants.me();
  * console.log(`Tenant: ${tenant.name} (${tenant.tier})`);
  *
- * // Check resource usage
- * const usage = await nexus.tenants.usage();
- * console.log(`Memories: ${usage.memories_count}`);
+ * // Check usage statistics for the last week
+ * const usage = await nexus.tenants.usage('week');
+ * console.log(`API calls: ${usage.api_calls} (${usage.success_rate}% ok)`);
  * ```
  */
 declare class TenantService extends BaseService {
@@ -1916,14 +1939,17 @@ declare class TenantService extends BaseService {
      */
     me(options?: RequestOptions): Promise<Tenant>;
     /**
-     * Retrieve the current tenant's resource usage statistics.
+     * Retrieve the current tenant's usage statistics.
      *
-     * Returns counts for memories, conversations, and today's API calls.
-     * Useful for monitoring quota consumption and building dashboards.
+     * Returns API-call counts, success rate, latency percentiles, resource
+     * counts, and storage usage for the requested period — the backend
+     * `UsageStatsResponse` shape (v3.0.0: previously mistyped as a 3-field
+     * `TenantUsage` that never matched the wire).
      *
-     * @returns Current resource usage for the authenticated tenant.
+     * @param period - Statistics window: `'day'` (default) | `'week'` | `'month'`.
+     * @returns Usage statistics for the authenticated tenant.
      */
-    usage(options?: RequestOptions): Promise<TenantUsage>;
+    usage(period?: 'day' | 'week' | 'month', options?: RequestOptions): Promise<UsageStats>;
     /**
      * List all API keys for the current tenant.
      *
@@ -2504,22 +2530,6 @@ declare const messageCreateSchema: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
 }>;
 
-declare const entityCreateSchema: z.ZodObject<{
-    name: z.ZodString;
-    entity_type: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    entity_type: string;
-    description?: string | undefined;
-    properties?: Record<string, unknown> | undefined;
-}, {
-    name: string;
-    entity_type: string;
-    description?: string | undefined;
-    properties?: Record<string, unknown> | undefined;
-}>;
 declare const graphQueryRequestSchema: z.ZodObject<{
     entity_name: z.ZodString;
     depth: z.ZodOptional<z.ZodNumber>;
@@ -2549,16 +2559,16 @@ declare const extractionRequestSchema: z.ZodObject<{
 
 declare const apiKeyCreateSchema: z.ZodObject<{
     name: z.ZodString;
-    scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<["read", "write", "admin"]>, "many">>;
-    expires_days: z.ZodOptional<z.ZodNumber>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    expires_in_days: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    scopes?: ("read" | "write" | "admin")[] | undefined;
-    expires_days?: number | undefined;
+    scopes?: string[] | undefined;
+    expires_in_days?: number | undefined;
 }, {
     name: string;
-    scopes?: ("read" | "write" | "admin")[] | undefined;
-    expires_days?: number | undefined;
+    scopes?: string[] | undefined;
+    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 ApiKeyScope, 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 ConversationDetail, type ConversationList, type ConversationListParams, type ConversationMessage, ConversationService, type ConversationStatus, type ConversationSummary, DEFAULT_CONFIG, DEPTH_PRESETS, type EntityCreate, 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, type TenantUsage, TimeoutError, type UsageStats, ValidationError, apiKeyCreateSchema, contextRequestSchema, conversationCreateSchema, entityCreateSchema, 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 ConversationDetail, 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 };