@lanonasis/memory-client 2.0.0 → 2.1.0

package/dist/core/index.js

@@ -1,5 +1,221 @@
 import { z } from 'zod';
 
+/**
+ * Memory types supported by the service
+ */
+const MEMORY_TYPES = ['context', 'project', 'knowledge', 'reference', 'personal', 'workflow'];
+/**
+ * Memory status values
+ */
+const MEMORY_STATUSES = ['active', 'archived', 'draft', 'deleted'];
+/**
+ * Validation schemas using Zod
+ */
+const createMemorySchema = z.object({
+    title: z.string().min(1).max(500),
+    content: z.string().min(1).max(50000),
+    summary: z.string().max(1000).optional(),
+    memory_type: z.enum(MEMORY_TYPES).default('context'),
+    topic_id: z.string().uuid().optional(),
+    project_ref: z.string().max(100).optional(),
+    tags: z.array(z.string().min(1).max(50)).max(20).default([]),
+    metadata: z.record(z.string(), z.unknown()).optional()
+});
+const updateMemorySchema = z.object({
+    title: z.string().min(1).max(500).optional(),
+    content: z.string().min(1).max(50000).optional(),
+    summary: z.string().max(1000).optional(),
+    memory_type: z.enum(MEMORY_TYPES).optional(),
+    status: z.enum(MEMORY_STATUSES).optional(),
+    topic_id: z.string().uuid().nullable().optional(),
+    project_ref: z.string().max(100).nullable().optional(),
+    tags: z.array(z.string().min(1).max(50)).max(20).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+});
+const searchMemorySchema = z.object({
+    query: z.string().min(1).max(1000),
+    memory_types: z.array(z.enum(MEMORY_TYPES)).optional(),
+    tags: z.array(z.string()).optional(),
+    topic_id: z.string().uuid().optional(),
+    project_ref: z.string().optional(),
+    status: z.enum(MEMORY_STATUSES).default('active'),
+    limit: z.number().int().min(1).max(100).default(20),
+    threshold: z.number().min(0).max(1).default(0.7)
+});
+const createTopicSchema = z.object({
+    name: z.string().min(1).max(100),
+    description: z.string().max(500).optional(),
+    color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional(),
+    icon: z.string().max(50).optional(),
+    parent_topic_id: z.string().uuid().optional()
+});
+// ========================================
+// Intelligence Feature Types (v2.0)
+// ========================================
+/**
+ * Chunking strategies for content preprocessing
+ */
+const CHUNKING_STRATEGIES = ['semantic', 'fixed-size', 'paragraph', 'sentence', 'code-block'];
+/**
+ * Content types detected or specified
+ */
+const CONTENT_TYPES = ['text', 'code', 'markdown', 'json', 'yaml'];
+// ========================================
+// Enhanced Search Types
+// ========================================
+/**
+ * Search modes for memory queries
+ */
+const SEARCH_MODES = ['vector', 'text', 'hybrid'];
+// ========================================
+// Validation Schemas for Intelligence
+// ========================================
+const preprocessingOptionsSchema = z.object({
+    chunking: z.object({
+        strategy: z.enum(CHUNKING_STRATEGIES).optional(),
+        maxChunkSize: z.number().int().min(100).max(10000).optional(),
+        overlap: z.number().int().min(0).max(500).optional()
+    }).optional(),
+    cleanContent: z.boolean().optional(),
+    extractMetadata: z.boolean().optional()
+}).optional();
+const enhancedSearchSchema = z.object({
+    query: z.string().min(1).max(1000),
+    type: z.enum(MEMORY_TYPES).optional(),
+    threshold: z.number().min(0).max(1).default(0.7),
+    limit: z.number().int().min(1).max(100).default(20),
+    search_mode: z.enum(SEARCH_MODES).default('hybrid'),
+    filters: z.object({
+        tags: z.array(z.string()).optional(),
+        project_id: z.string().uuid().optional(),
+        topic_id: z.string().uuid().optional(),
+        date_range: z.object({
+            from: z.string().optional(),
+            to: z.string().optional()
+        }).optional()
+    }).optional(),
+    include_chunks: z.boolean().default(false)
+});
+const analyticsDateRangeSchema = z.object({
+    from: z.string().optional(),
+    to: z.string().optional(),
+    group_by: z.enum(['day', 'week', 'month']).default('day')
+});
+
+/**
+ * Core Utilities for Memory Client
+ * Browser-safe, no Node.js dependencies
+ */
+/**
+ * Safely parse JSON with detailed error reporting
+ * Prevents scattered try/catch blocks throughout the codebase
+ */
+function safeJsonParse(input) {
+    try {
+        const data = JSON.parse(input);
+        return { success: true, data };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.message
+            : 'Unknown JSON parse error';
+        return { success: false, error: `Invalid JSON: ${message}` };
+    }
+}
+/**
+ * HTTP status code to error code mapping
+ */
+function httpStatusToErrorCode(status) {
+    switch (status) {
+        case 400:
+            return 'VALIDATION_ERROR';
+        case 401:
+            return 'AUTH_ERROR';
+        case 403:
+            return 'FORBIDDEN';
+        case 404:
+            return 'NOT_FOUND';
+        case 408:
+            return 'TIMEOUT_ERROR';
+        case 409:
+            return 'CONFLICT';
+        case 429:
+            return 'RATE_LIMIT_ERROR';
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return 'SERVER_ERROR';
+        default:
+            return 'API_ERROR';
+    }
+}
+/**
+ * Create a standardized error response from various error sources
+ */
+function createErrorResponse(message, code = 'API_ERROR', statusCode, details) {
+    return {
+        code,
+        message,
+        statusCode,
+        details,
+        timestamp: new Date().toISOString()
+    };
+}
+/**
+ * Create an error response from an HTTP response
+ */
+function createErrorFromResponse(status, statusText, body) {
+    const code = httpStatusToErrorCode(status);
+    // Try to extract message from response body
+    let message = `HTTP ${status}: ${statusText}`;
+    let details = undefined;
+    if (body && typeof body === 'object') {
+        const bodyObj = body;
+        if (typeof bodyObj.error === 'string') {
+            message = bodyObj.error;
+        }
+        else if (typeof bodyObj.message === 'string') {
+            message = bodyObj.message;
+        }
+        if (bodyObj.details) {
+            details = bodyObj.details;
+        }
+    }
+    return createErrorResponse(message, code, status, details);
+}
+/**
+ * Sleep utility for retry logic
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Calculate retry delay with exponential backoff and jitter
+ */
+function calculateRetryDelay(attempt, baseDelay = 1000, backoff = 'exponential', maxDelay = 30000) {
+    let delay;
+    if (backoff === 'exponential') {
+        delay = baseDelay * Math.pow(2, attempt);
+    }
+    else {
+        delay = baseDelay * (attempt + 1);
+    }
+    // Add jitter (±20%) to prevent thundering herd
+    const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+    delay = Math.min(delay + jitter, maxDelay);
+    return Math.round(delay);
+}
+/**
+ * Check if an error is retryable based on status code
+ */
+function isRetryableError(statusCode) {
+    if (!statusCode)
+        return true; // Network errors are retryable
+    // Retry on server errors and rate limits
+    return statusCode >= 500 || statusCode === 429 || statusCode === 408;
+}
+
 /**
  * Core Memory Client - Pure Browser-Safe Implementation
  *
@@ -8,6 +224,18 @@ import { z } from 'zod';
  *
  * Bundle size: ~15KB gzipped
  */
+/**
+ * Helper to check if response has error
+ */
+function hasError(response) {
+    return response.error !== undefined;
+}
+/**
+ * Helper to check if response has data
+ */
+function hasData(response) {
+    return response.data !== undefined;
+}
 /**
  * Core Memory Client class for interacting with the Memory as a Service API
  *
@@ -23,6 +251,7 @@ class CoreMemoryClient {
         this.baseHeaders = {
             'Content-Type': 'application/json',
             'User-Agent': '@lanonasis/memory-client/2.0.0',
+            'X-Project-Scope': 'lanonasis-maas', // Required by backend auth middleware
             ...config.headers
         };
         // Set authentication headers
@@ -59,10 +288,13 @@ class CoreMemoryClient {
         return body;
     }
     /**
-     * Make an HTTP request to the API
+     * Make an HTTP request to the API with retry support
      */
     async request(endpoint, options = {}) {
         const startTime = Date.now();
+        const maxRetries = this.config.retry?.maxRetries ?? 3;
+        const baseDelay = this.config.retry?.retryDelay ?? 1000;
+        const backoff = this.config.retry?.backoff ?? 'exponential';
         // Call onRequest hook if provided
         if (this.config.onRequest) {
             try {
@@ -77,85 +309,123 @@ class CoreMemoryClient {
             ? this.config.apiUrl.replace('/api', '')
             : this.config.apiUrl;
         const url = `${baseUrl}/api/v1${endpoint}`;
-        try {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-            const response = await fetch(url, {
-                headers: { ...this.baseHeaders, ...options.headers },
-                signal: controller.signal,
-                ...options,
-            });
-            clearTimeout(timeoutId);
-            let data;
-            const contentType = response.headers.get('content-type');
-            if (contentType && contentType.includes('application/json')) {
-                data = await response.json();
-            }
-            else {
-                data = await response.text();
-            }
-            if (!response.ok) {
-                const error = {
-                    message: data?.error || `HTTP ${response.status}: ${response.statusText}`,
-                    statusCode: response.status,
-                    code: 'API_ERROR'
-                };
-                // Call onError hook if provided
-                if (this.config.onError) {
+        let lastError;
+        let attempt = 0;
+        while (attempt <= maxRetries) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+                const response = await fetch(url, {
+                    headers: { ...this.baseHeaders, ...options.headers },
+                    signal: controller.signal,
+                    ...options,
+                });
+                clearTimeout(timeoutId);
+                let data;
+                const contentType = response.headers.get('content-type');
+                if (contentType && contentType.includes('application/json')) {
+                    data = await response.json();
+                }
+                else {
+                    data = await response.text();
+                }
+                if (!response.ok) {
+                    const error = createErrorFromResponse(response.status, response.statusText, data);
+                    // Only retry on retryable errors (5xx, 429, 408)
+                    if (isRetryableError(response.status) && attempt < maxRetries) {
+                        lastError = error;
+                        const delay = calculateRetryDelay(attempt, baseDelay, backoff);
+                        await sleep(delay);
+                        attempt++;
+                        continue;
+                    }
+                    // Call onError hook if provided
+                    if (this.config.onError) {
+                        try {
+                            this.config.onError(error);
+                        }
+                        catch (hookError) {
+                            console.warn('onError hook error:', hookError);
+                        }
+                    }
+                    return { error, meta: { duration: Date.now() - startTime, retries: attempt } };
+                }
+                // Call onResponse hook if provided
+                if (this.config.onResponse) {
                     try {
-                        this.config.onError(error);
+                        const duration = Date.now() - startTime;
+                        this.config.onResponse(endpoint, duration);
                     }
-                    catch (hookError) {
-                        console.warn('onError hook error:', hookError);
+                    catch (error) {
+                        console.warn('onResponse hook error:', error);
                     }
                 }
-                return { error: error.message };
+                return { data, meta: { duration: Date.now() - startTime, retries: attempt } };
             }
-            // Call onResponse hook if provided
-            if (this.config.onResponse) {
-                try {
-                    const duration = Date.now() - startTime;
-                    this.config.onResponse(endpoint, duration);
+            catch (error) {
+                if (error instanceof Error && error.name === 'AbortError') {
+                    const timeoutError = createErrorResponse('Request timeout', 'TIMEOUT_ERROR', 408);
+                    // Retry on timeout
+                    if (attempt < maxRetries) {
+                        lastError = timeoutError;
+                        const delay = calculateRetryDelay(attempt, baseDelay, backoff);
+                        await sleep(delay);
+                        attempt++;
+                        continue;
+                    }
+                    if (this.config.onError) {
+                        try {
+                            this.config.onError(timeoutError);
+                        }
+                        catch (hookError) {
+                            console.warn('onError hook error:', hookError);
+                        }
+                    }
+                    return { error: timeoutError, meta: { duration: Date.now() - startTime, retries: attempt } };
                 }
-                catch (error) {
-                    console.warn('onResponse hook error:', error);
+                const networkError = createErrorResponse(error instanceof Error ? error.message : 'Network error', 'NETWORK_ERROR');
+                // Retry on network errors
+                if (attempt < maxRetries) {
+                    lastError = networkError;
+                    const delay = calculateRetryDelay(attempt, baseDelay, backoff);
+                    await sleep(delay);
+                    attempt++;
+                    continue;
                 }
-            }
-            return { data };
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                const timeoutError = {
-                    message: 'Request timeout',
-                    code: 'TIMEOUT_ERROR',
-                    statusCode: 408
-                };
                 if (this.config.onError) {
                     try {
-                        this.config.onError(timeoutError);
+                        this.config.onError(networkError);
                     }
                     catch (hookError) {
                         console.warn('onError hook error:', hookError);
                     }
                 }
-                return { error: 'Request timeout' };
-            }
-            const networkError = {
-                message: error instanceof Error ? error.message : 'Network error',
-                code: 'NETWORK_ERROR'
-            };
-            if (this.config.onError) {
-                try {
-                    this.config.onError(networkError);
-                }
-                catch (hookError) {
-                    console.warn('onError hook error:', hookError);
-                }
+                return { error: networkError, meta: { duration: Date.now() - startTime, retries: attempt } };
             }
+        }
+        // Should never reach here, but handle it gracefully
+        return {
+            error: lastError ?? createErrorResponse('Max retries exceeded', 'API_ERROR'),
+            meta: { duration: Date.now() - startTime, retries: attempt }
+        };
+    }
+    /**
+     * Validate input using Zod schema and return validation error if invalid
+     */
+    validateInput(schema, data) {
+        const result = schema.safeParse(data);
+        if (!result.success) {
+            // Extract error details from Zod error
+            const zodError = result.error;
+            const details = zodError?.issues?.map(issue => ({
+                field: issue.path.map(String).join('.'),
+                message: issue.message
+            })) ?? [];
             return {
-                error: error instanceof Error ? error.message : 'Network error'
+                error: createErrorResponse('Validation failed', 'VALIDATION_ERROR', 400, details)
             };
         }
+        return null;
     }
     /**
      * Test the API connection and authentication
@@ -165,9 +435,14 @@ class CoreMemoryClient {
     }
     // Memory Operations
     /**
-     * Create a new memory
+     * Create a new memory with validation
      */
     async createMemory(memory) {
+        // Validate input before making request
+        const validationError = this.validateInput(createMemorySchema, memory);
+        if (validationError) {
+            return { error: validationError.error };
+        }
         const enrichedMemory = this.enrichWithOrgContext(memory);
         return this.request('/memory', {
             method: 'POST',
@@ -181,9 +456,14 @@ class CoreMemoryClient {
         return this.request(`/memory/${encodeURIComponent(id)}`);
     }
     /**
-     * Update an existing memory
+     * Update an existing memory with validation
      */
     async updateMemory(id, updates) {
+        // Validate input before making request
+        const validationError = this.validateInput(updateMemorySchema, updates);
+        if (validationError) {
+            return { error: validationError.error };
+        }
         return this.request(`/memory/${encodeURIComponent(id)}`, {
             method: 'PUT',
             body: JSON.stringify(updates)
@@ -217,9 +497,15 @@ class CoreMemoryClient {
         return this.request(endpoint);
     }
     /**
-     * Search memories using semantic search
+     * Search memories using semantic search with validation
      */
     async searchMemories(request) {
+        // Validate input before making request
+        const validationError = this.validateInput(searchMemorySchema, request);
+        if (validationError) {
+            // Return error response (data will be undefined, only error is set)
+            return { error: validationError.error };
+        }
         const enrichedRequest = this.enrichWithOrgContext(request);
         return this.request('/memory/search', {
             method: 'POST',
@@ -238,9 +524,14 @@ class CoreMemoryClient {
     }
     // Topic Operations
     /**
-     * Create a new topic
+     * Create a new topic with validation
      */
     async createTopic(topic) {
+        // Validate input before making request
+        const validationError = this.validateInput(createTopicSchema, topic);
+        if (validationError) {
+            return { error: validationError.error };
+        }
         const enrichedTopic = this.enrichWithOrgContext(topic);
         return this.request('/topics', {
             method: 'POST',
@@ -282,6 +573,182 @@ class CoreMemoryClient {
     async getMemoryStats() {
         return this.request('/memory/stats');
     }
+    // ========================================
+    // Intelligence Features (v2.0)
+    // ========================================
+    /**
+     * Create a memory with preprocessing options (chunking, intelligence extraction)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.createMemoryWithPreprocessing({
+     *   title: 'Auth System Docs',
+     *   content: 'Long content...',
+     *   memory_type: 'knowledge',
+     *   preprocessing: {
+     *     chunking: { strategy: 'semantic', maxChunkSize: 1000 },
+     *     extractMetadata: true
+     *   }
+     * });
+     * ```
+     */
+    async createMemoryWithPreprocessing(memory) {
+        // Validate base memory fields
+        const validationError = this.validateInput(createMemorySchema, memory);
+        if (validationError) {
+            return { error: validationError.error };
+        }
+        const enrichedMemory = this.enrichWithOrgContext(memory);
+        return this.request('/memory', {
+            method: 'POST',
+            body: JSON.stringify(enrichedMemory)
+        });
+    }
+    /**
+     * Update a memory with re-chunking and embedding regeneration
+     *
+     * @example
+     * ```typescript
+     * const result = await client.updateMemoryWithPreprocessing('mem_123', {
+     *   content: 'Updated content...',
+     *   rechunk: true,
+     *   regenerate_embedding: true
+     * });
+     * ```
+     */
+    async updateMemoryWithPreprocessing(id, updates) {
+        const validationError = this.validateInput(updateMemorySchema, updates);
+        if (validationError) {
+            return { error: validationError.error };
+        }
+        return this.request(`/memory/${encodeURIComponent(id)}`, {
+            method: 'PUT',
+            body: JSON.stringify(updates)
+        });
+    }
+    /**
+     * Enhanced semantic search with hybrid mode (vector + text)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.enhancedSearch({
+     *   query: 'authentication flow',
+     *   search_mode: 'hybrid',
+     *   filters: { tags: ['auth'], project_id: 'proj_123' },
+     *   include_chunks: true
+     * });
+     * ```
+     */
+    async enhancedSearch(request) {
+        const validationError = this.validateInput(enhancedSearchSchema, request);
+        if (validationError) {
+            return { error: validationError.error };
+        }
+        const enrichedRequest = this.enrichWithOrgContext(request);
+        return this.request('/memory/search', {
+            method: 'POST',
+            body: JSON.stringify(enrichedRequest)
+        });
+    }
+    // ========================================
+    // Analytics Operations
+    // ========================================
+    /**
+     * Get search analytics data
+     *
+     * @example
+     * ```typescript
+     * const analytics = await client.getSearchAnalytics({
+     *   from: '2025-01-01',
+     *   to: '2025-12-31',
+     *   group_by: 'day'
+     * });
+     * ```
+     */
+    async getSearchAnalytics(options = {}) {
+        const validationError = this.validateInput(analyticsDateRangeSchema, options);
+        if (validationError) {
+            return { error: validationError.error };
+        }
+        const params = new URLSearchParams();
+        if (options.from)
+            params.append('from', options.from);
+        if (options.to)
+            params.append('to', options.to);
+        if (options.group_by)
+            params.append('group_by', options.group_by);
+        const queryString = params.toString();
+        const endpoint = queryString ? `/analytics/search?${queryString}` : '/analytics/search';
+        return this.request(endpoint);
+    }
+    /**
+     * Get memory access patterns
+     *
+     * @example
+     * ```typescript
+     * const patterns = await client.getAccessPatterns({
+     *   from: '2025-01-01',
+     *   to: '2025-12-31'
+     * });
+     * console.log(patterns.data?.most_accessed);
+     * ```
+     */
+    async getAccessPatterns(options = {}) {
+        const params = new URLSearchParams();
+        if (options.from)
+            params.append('from', options.from);
+        if (options.to)
+            params.append('to', options.to);
+        const queryString = params.toString();
+        const endpoint = queryString ? `/analytics/access?${queryString}` : '/analytics/access';
+        return this.request(endpoint);
+    }
+    /**
+     * Get extended memory statistics with storage and activity metrics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.getExtendedStats();
+     * console.log(`Total chunks: ${stats.data?.storage.total_chunks}`);
+     * console.log(`Created today: ${stats.data?.activity.created_today}`);
+     * ```
+     */
+    async getExtendedStats() {
+        return this.request('/analytics/stats');
+    }
+    /**
+     * Get topic with its memories
+     *
+     * @example
+     * ```typescript
+     * const topic = await client.getTopicWithMemories('topic_123');
+     * console.log(topic.data?.memories);
+     * ```
+     */
+    async getTopicWithMemories(topicId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit)
+            params.append('limit', String(options.limit));
+        if (options.offset)
+            params.append('offset', String(options.offset));
+        const queryString = params.toString();
+        const endpoint = queryString
+            ? `/topics/${encodeURIComponent(topicId)}/memories?${queryString}`
+            : `/topics/${encodeURIComponent(topicId)}/memories`;
+        return this.request(endpoint);
+    }
+    /**
+     * Get topics in hierarchical structure
+     *
+     * @example
+     * ```typescript
+     * const topics = await client.getTopicsHierarchy();
+     * // Returns nested topic tree with children
+     * ```
+     */
+    async getTopicsHierarchy() {
+        return this.request('/topics?include_hierarchy=true');
+    }
     // Utility Methods
     /**
      * Update authentication token
@@ -330,64 +797,40 @@ function createMemoryClient(config) {
 }
 
 /**
- * Memory types supported by the service
+ * Error handling for Memory Client
+ * Browser-safe, no Node.js dependencies
  */
-const MEMORY_TYPES = ['context', 'project', 'knowledge', 'reference', 'personal', 'workflow'];
 /**
- * Memory status values
+ * Standardized error codes for programmatic error handling
  */
-const MEMORY_STATUSES = ['active', 'archived', 'draft', 'deleted'];
+const ERROR_CODES = [
+    'API_ERROR',
+    'AUTH_ERROR',
+    'VALIDATION_ERROR',
+    'TIMEOUT_ERROR',
+    'RATE_LIMIT_ERROR',
+    'NOT_FOUND',
+    'NETWORK_ERROR',
+    'FORBIDDEN',
+    'CONFLICT',
+    'SERVER_ERROR'
+];
 /**
- * Validation schemas using Zod
- */
-const createMemorySchema = z.object({
-    title: z.string().min(1).max(500),
-    content: z.string().min(1).max(50000),
-    summary: z.string().max(1000).optional(),
-    memory_type: z.enum(MEMORY_TYPES).default('context'),
-    topic_id: z.string().uuid().optional(),
-    project_ref: z.string().max(100).optional(),
-    tags: z.array(z.string().min(1).max(50)).max(20).default([]),
-    metadata: z.record(z.string(), z.unknown()).optional()
-});
-const updateMemorySchema = z.object({
-    title: z.string().min(1).max(500).optional(),
-    content: z.string().min(1).max(50000).optional(),
-    summary: z.string().max(1000).optional(),
-    memory_type: z.enum(MEMORY_TYPES).optional(),
-    status: z.enum(MEMORY_STATUSES).optional(),
-    topic_id: z.string().uuid().nullable().optional(),
-    project_ref: z.string().max(100).nullable().optional(),
-    tags: z.array(z.string().min(1).max(50)).max(20).optional(),
-    metadata: z.record(z.string(), z.unknown()).optional()
-});
-const searchMemorySchema = z.object({
-    query: z.string().min(1).max(1000),
-    memory_types: z.array(z.enum(MEMORY_TYPES)).optional(),
-    tags: z.array(z.string()).optional(),
-    topic_id: z.string().uuid().optional(),
-    project_ref: z.string().optional(),
-    status: z.enum(MEMORY_STATUSES).default('active'),
-    limit: z.number().int().min(1).max(100).default(20),
-    threshold: z.number().min(0).max(1).default(0.7)
-});
-const createTopicSchema = z.object({
-    name: z.string().min(1).max(100),
-    description: z.string().max(500).optional(),
-    color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional(),
-    icon: z.string().max(50).optional(),
-    parent_topic_id: z.string().uuid().optional()
-});
-
-/**
- * Error handling for Memory Client
- * Browser-safe, no Node.js dependencies
+ * Type guard to check if an object is an ApiErrorResponse
  */
+function isApiErrorResponse(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'code' in value &&
+        'message' in value &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string');
+}
 /**
  * Base error class for Memory Client errors
  */
 class MemoryClientError extends Error {
-    constructor(message, code, statusCode, details) {
+    constructor(message, code = 'API_ERROR', statusCode, details) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
@@ -398,6 +841,18 @@ class MemoryClientError extends Error {
             Error.captureStackTrace(this, MemoryClientError);
         }
     }
+    /**
+     * Convert to ApiErrorResponse for consistent API responses
+     */
+    toResponse() {
+        return {
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            details: this.details,
+            timestamp: new Date().toISOString()
+        };
+    }
 }
 /**
  * Network/API error
@@ -407,6 +862,26 @@ class ApiError extends MemoryClientError {
         super(message, 'API_ERROR', statusCode, details);
         this.name = 'ApiError';
     }
+    /**
+     * Create from an HTTP response
+     */
+    static fromResponse(status, statusText, body) {
+        let message = `HTTP ${status}: ${statusText}`;
+        let details = undefined;
+        if (body && typeof body === 'object') {
+            const bodyObj = body;
+            if (typeof bodyObj.error === 'string') {
+                message = bodyObj.error;
+            }
+            else if (typeof bodyObj.message === 'string') {
+                message = bodyObj.message;
+            }
+            if (bodyObj.details) {
+                details = bodyObj.details;
+            }
+        }
+        return new ApiError(message, status, details);
+    }
 }
 /**
  * Authentication error
@@ -418,12 +893,30 @@ class AuthenticationError extends MemoryClientError {
     }
 }
 /**
- * Validation error
+ * Validation error with field-level details
  */
 class ValidationError extends MemoryClientError {
     constructor(message, details) {
         super(message, 'VALIDATION_ERROR', 400, details);
         this.name = 'ValidationError';
+        // Parse validation details into field errors
+        this.validationErrors = [];
+        if (Array.isArray(details)) {
+            this.validationErrors = details.filter((item) => typeof item === 'object' &&
+                item !== null &&
+                typeof item.field === 'string' &&
+                typeof item.message === 'string');
+        }
+    }
+    /**
+     * Create from Zod error
+     */
+    static fromZodError(error) {
+        const details = error.issues.map(issue => ({
+            field: issue.path.join('.'),
+            message: issue.message
+        }));
+        return new ValidationError('Validation failed', details);
     }
 }
 /**
@@ -436,12 +929,13 @@ class TimeoutError extends MemoryClientError {
     }
 }
 /**
- * Rate limit error
+ * Rate limit error with retry-after info
  */
 class RateLimitError extends MemoryClientError {
-    constructor(message = 'Rate limit exceeded') {
-        super(message, 'RATE_LIMIT_ERROR', 429);
+    constructor(message = 'Rate limit exceeded', retryAfter) {
+        super(message, 'RATE_LIMIT_ERROR', 429, { retryAfter });
         this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
     }
 }
 /**
@@ -451,6 +945,49 @@ class NotFoundError extends MemoryClientError {
     constructor(resource) {
         super(`${resource} not found`, 'NOT_FOUND', 404);
         this.name = 'NotFoundError';
+        this.resource = resource;
+    }
+}
+/**
+ * Network error (no response received)
+ */
+class NetworkError extends MemoryClientError {
+    constructor(message = 'Network error') {
+        super(message, 'NETWORK_ERROR');
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Server error (5xx responses)
+ */
+class ServerError extends MemoryClientError {
+    constructor(message, statusCode = 500) {
+        super(message, 'SERVER_ERROR', statusCode);
+        this.name = 'ServerError';
+    }
+}
+/**
+ * Create appropriate error class from status code
+ */
+function createErrorFromStatus(status, message, details) {
+    switch (status) {
+        case 400:
+            return new ValidationError(message, details);
+        case 401:
+            return new AuthenticationError(message);
+        case 404:
+            return new NotFoundError(message);
+        case 408:
+            return new TimeoutError(message);
+        case 429:
+            return new RateLimitError(message);
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return new ServerError(message, status);
+        default:
+            return new ApiError(message, status, details);
     }
 }
 
@@ -486,5 +1023,5 @@ const defaultConfigs = {
     }
 };
 
-export { ApiError as ApiErrorClass, AuthenticationError, CLIENT_NAME, CoreMemoryClient, MEMORY_STATUSES, MEMORY_TYPES, MemoryClientError, NotFoundError, RateLimitError, TimeoutError, VERSION, ValidationError, createMemoryClient, createMemorySchema, createTopicSchema, defaultConfigs, isBrowser, isNode, searchMemorySchema, updateMemorySchema };
+export { ApiError, AuthenticationError, CHUNKING_STRATEGIES, CLIENT_NAME, CONTENT_TYPES, CoreMemoryClient, ERROR_CODES, MEMORY_STATUSES, MEMORY_TYPES, MemoryClientError, NetworkError, NotFoundError, RateLimitError, SEARCH_MODES, ServerError, TimeoutError, VERSION, ValidationError, analyticsDateRangeSchema, calculateRetryDelay, createErrorFromStatus, createErrorResponse, createMemoryClient, createMemorySchema, createTopicSchema, defaultConfigs, enhancedSearchSchema, hasData, hasError, httpStatusToErrorCode, isApiErrorResponse, isBrowser, isNode, isRetryableError, preprocessingOptionsSchema, safeJsonParse, searchMemorySchema, updateMemorySchema };
 //# sourceMappingURL=index.js.map