@lanonasis/memory-client 2.0.0 → 2.2.0

package/dist/core/index.d.ts

@@ -142,6 +142,414 @@ type CreateMemoryRequest = z.infer<typeof createMemorySchema>;
 type UpdateMemoryRequest = z.infer<typeof updateMemorySchema>;
 type SearchMemoryRequest = z.infer<typeof searchMemorySchema>;
 type CreateTopicRequest = z.infer<typeof createTopicSchema>;
+/**
+ * Chunking strategies for content preprocessing
+ */
+declare const CHUNKING_STRATEGIES: readonly ["semantic", "fixed-size", "paragraph", "sentence", "code-block"];
+type ChunkingStrategy = typeof CHUNKING_STRATEGIES[number];
+/**
+ * Content types detected or specified
+ */
+declare const CONTENT_TYPES: readonly ["text", "code", "markdown", "json", "yaml"];
+type ContentType = typeof CONTENT_TYPES[number];
+/**
+ * A chunk of content from a memory entry
+ */
+interface ContentChunk {
+    index: number;
+    content: string;
+    startChar: number;
+    endChar: number;
+    tokens: number;
+    metadata?: {
+        type: 'paragraph' | 'sentence' | 'code' | 'section';
+        isComplete: boolean;
+    };
+}
+/**
+ * Extracted intelligence from memory content
+ */
+interface MemoryIntelligence {
+    entities: string[];
+    keywords: string[];
+    language: string;
+    topics?: string[];
+    sentiment?: 'positive' | 'neutral' | 'negative';
+    complexity?: 'low' | 'medium' | 'high';
+}
+/**
+ * Extended metadata with intelligence features
+ */
+interface IntelligentMetadata extends Record<string, unknown> {
+    chunks?: ContentChunk[];
+    total_chunks?: number;
+    chunking_strategy?: ChunkingStrategy;
+    last_rechunked_at?: string;
+    intelligence?: MemoryIntelligence;
+    content_type?: ContentType;
+    language?: string;
+    tokens?: number;
+    source?: string;
+    priority?: 'high' | 'medium' | 'low';
+}
+/**
+ * Preprocessing options for memory creation/update
+ */
+interface PreprocessingOptions {
+    chunking?: {
+        strategy?: ChunkingStrategy;
+        maxChunkSize?: number;
+        overlap?: number;
+    };
+    cleanContent?: boolean;
+    extractMetadata?: boolean;
+}
+/**
+ * Extended create memory request with preprocessing
+ */
+interface CreateMemoryWithPreprocessingRequest extends CreateMemoryRequest {
+    preprocessing?: PreprocessingOptions;
+    metadata?: IntelligentMetadata;
+}
+/**
+ * Extended update memory request with re-chunking
+ */
+interface UpdateMemoryWithPreprocessingRequest extends UpdateMemoryRequest {
+    rechunk?: boolean;
+    regenerate_embedding?: boolean;
+}
+/**
+ * Search modes for memory queries
+ */
+declare const SEARCH_MODES: readonly ["vector", "text", "hybrid"];
+type SearchMode = typeof SEARCH_MODES[number];
+/**
+ * A matching chunk from search results
+ */
+interface MatchingChunk {
+    index: number;
+    content: string;
+    similarity: number;
+}
+/**
+ * Enhanced search filters
+ */
+interface SearchFilters {
+    tags?: string[];
+    project_id?: string;
+    topic_id?: string;
+    date_range?: {
+        from?: string;
+        to?: string;
+    };
+}
+/**
+ * Enhanced search request with hybrid mode
+ */
+interface EnhancedSearchRequest {
+    query: string;
+    type?: MemoryType;
+    threshold?: number;
+    limit?: number;
+    search_mode?: SearchMode;
+    filters?: SearchFilters;
+    include_chunks?: boolean;
+}
+/**
+ * Enhanced search result with chunk matching
+ */
+interface EnhancedMemorySearchResult extends MemorySearchResult {
+    text_rank?: number;
+    combined_score?: number;
+    matching_chunks?: MatchingChunk[];
+}
+/**
+ * Enhanced search response
+ */
+interface EnhancedSearchResponse {
+    results: EnhancedMemorySearchResult[];
+    total: number;
+    query: string;
+    search_mode: SearchMode;
+    threshold: number;
+    execution_time_ms: number;
+}
+/**
+ * Search analytics data point
+ */
+interface SearchAnalyticsDataPoint {
+    date: string;
+    searches: number;
+    avg_results: number;
+    avg_time_ms: number;
+}
+/**
+ * Popular query entry
+ */
+interface PopularQuery {
+    query: string;
+    count: number;
+    avg_results: number;
+}
+/**
+ * Search analytics response
+ */
+interface SearchAnalytics {
+    total_searches: number;
+    avg_results_count: number;
+    avg_execution_time_ms: number;
+    search_types: {
+        vector: number;
+        text: number;
+        hybrid: number;
+    };
+    by_date: SearchAnalyticsDataPoint[];
+    popular_queries: PopularQuery[];
+}
+/**
+ * Most accessed memory entry
+ */
+interface MostAccessedMemory {
+    memory_id: string;
+    title: string;
+    access_count: number;
+    last_accessed: string;
+}
+/**
+ * Hourly access data
+ */
+interface HourlyAccess {
+    hour: number;
+    count: number;
+}
+/**
+ * Access patterns response
+ */
+interface AccessPatterns {
+    total_accesses: number;
+    by_type: {
+        read: number;
+        update: number;
+        delete: number;
+    };
+    by_method: {
+        api: number;
+        search: number;
+        direct: number;
+    };
+    most_accessed: MostAccessedMemory[];
+    access_by_hour: HourlyAccess[];
+}
+/**
+ * Project memory count
+ */
+interface ProjectMemoryCount {
+    project_id: string;
+    project_name: string;
+    count: number;
+}
+/**
+ * Tag count entry
+ */
+interface TagCount {
+    tag: string;
+    count: number;
+}
+/**
+ * Extended memory statistics
+ */
+interface ExtendedMemoryStats {
+    total_memories: number;
+    by_type: Record<MemoryType, number>;
+    by_project: ProjectMemoryCount[];
+    storage: {
+        total_size_mb: number;
+        avg_memory_size_kb: number;
+        total_chunks: number;
+    };
+    activity: {
+        created_today: number;
+        updated_today: number;
+        searched_today: number;
+    };
+    top_tags: TagCount[];
+}
+/**
+ * Analytics date range filter
+ */
+interface AnalyticsDateRange {
+    from?: string;
+    to?: string;
+    group_by?: 'day' | 'week' | 'month';
+}
+declare const preprocessingOptionsSchema: z.ZodOptional<z.ZodObject<{
+    chunking: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodOptional<z.ZodEnum<{
+            semantic: "semantic";
+            "fixed-size": "fixed-size";
+            paragraph: "paragraph";
+            sentence: "sentence";
+            "code-block": "code-block";
+        }>>;
+        maxChunkSize: z.ZodOptional<z.ZodNumber>;
+        overlap: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cleanContent: z.ZodOptional<z.ZodBoolean>;
+    extractMetadata: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+declare const enhancedSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        context: "context";
+        project: "project";
+        knowledge: "knowledge";
+        reference: "reference";
+        personal: "personal";
+        workflow: "workflow";
+    }>>;
+    threshold: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    search_mode: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        vector: "vector";
+        hybrid: "hybrid";
+    }>>;
+    filters: z.ZodOptional<z.ZodObject<{
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        project_id: z.ZodOptional<z.ZodString>;
+        topic_id: z.ZodOptional<z.ZodString>;
+        date_range: z.ZodOptional<z.ZodObject<{
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    include_chunks: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const analyticsDateRangeSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    group_by: z.ZodDefault<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+    }>>;
+}, z.core.$strip>;
+
+/**
+ * Error handling for Memory Client
+ * Browser-safe, no Node.js dependencies
+ */
+/**
+ * Standardized error codes for programmatic error handling
+ */
+declare const ERROR_CODES: readonly ["API_ERROR", "AUTH_ERROR", "VALIDATION_ERROR", "TIMEOUT_ERROR", "RATE_LIMIT_ERROR", "NOT_FOUND", "NETWORK_ERROR", "FORBIDDEN", "CONFLICT", "SERVER_ERROR"];
+type ErrorCode = typeof ERROR_CODES[number];
+/**
+ * Structured API error response - replaces plain string errors
+ * Enables programmatic error handling with typed codes
+ */
+interface ApiErrorResponse {
+    /** Machine-readable error code for programmatic handling */
+    code: ErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code if from API response */
+    statusCode?: number;
+    /** Additional error details (validation errors, etc.) */
+    details?: unknown;
+    /** Request ID for debugging/support */
+    requestId?: string;
+    /** Timestamp when error occurred */
+    timestamp?: string;
+}
+/**
+ * Type guard to check if an object is an ApiErrorResponse
+ */
+declare function isApiErrorResponse(value: unknown): value is ApiErrorResponse;
+/**
+ * Base error class for Memory Client errors
+ */
+declare class MemoryClientError extends Error {
+    code: ErrorCode;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code?: ErrorCode, statusCode?: number | undefined, details?: unknown | undefined);
+    /**
+     * Convert to ApiErrorResponse for consistent API responses
+     */
+    toResponse(): ApiErrorResponse;
+}
+/**
+ * Network/API error
+ */
+declare class ApiError extends MemoryClientError {
+    constructor(message: string, statusCode?: number, details?: unknown);
+    /**
+     * Create from an HTTP response
+     */
+    static fromResponse(status: number, statusText: string, body?: unknown): ApiError;
+}
+/**
+ * Authentication error
+ */
+declare class AuthenticationError extends MemoryClientError {
+    constructor(message?: string);
+}
+/**
+ * Validation error with field-level details
+ */
+declare class ValidationError extends MemoryClientError {
+    readonly validationErrors: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, details?: unknown);
+    /**
+     * Create from Zod error
+     */
+    static fromZodError(error: {
+        issues: Array<{
+            path: (string | number)[];
+            message: string;
+        }>;
+    }): ValidationError;
+}
+/**
+ * Timeout error
+ */
+declare class TimeoutError extends MemoryClientError {
+    constructor(message?: string);
+}
+/**
+ * Rate limit error with retry-after info
+ */
+declare class RateLimitError extends MemoryClientError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Not found error
+ */
+declare class NotFoundError extends MemoryClientError {
+    readonly resource: string;
+    constructor(resource: string);
+}
+/**
+ * Network error (no response received)
+ */
+declare class NetworkError extends MemoryClientError {
+    constructor(message?: string);
+}
+/**
+ * Server error (5xx responses)
+ */
+declare class ServerError extends MemoryClientError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Create appropriate error class from status code
+ */
+declare function createErrorFromStatus(status: number, message: string, details?: unknown): MemoryClientError;
 
 /**
  * Core Memory Client - Pure Browser-Safe Implementation
@@ -182,29 +590,41 @@ interface CoreMemoryClientConfig {
         ttl?: number;
     };
     /** Called when an error occurs */
-    onError?: (error: ApiError$1) => void;
+    onError?: (error: ApiErrorResponse) => void;
     /** Called before each request */
     onRequest?: (endpoint: string) => void;
     /** Called after each response */
     onResponse?: (endpoint: string, duration: number) => void;
 }
 /**
- * Standard API response wrapper
+ * Standard API response wrapper with typed errors
+ * Replaces string errors with structured ApiErrorResponse
  */
 interface ApiResponse<T> {
     data?: T;
-    error?: string;
+    /** Structured error response for programmatic handling */
+    error?: ApiErrorResponse;
+    /** Optional success message */
     message?: string;
+    /** Request metadata */
+    meta?: {
+        requestId?: string;
+        duration?: number;
+        retries?: number;
+    };
 }
 /**
- * API error with details
+ * Helper to check if response has error
  */
-interface ApiError$1 {
-    message: string;
-    code?: string;
-    statusCode?: number;
-    details?: unknown;
-}
+declare function hasError<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
+    error: ApiErrorResponse;
+};
+/**
+ * Helper to check if response has data
+ */
+declare function hasData<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
+    data: T;
+};
 /**
  * Paginated response for list operations
  */
@@ -233,9 +653,13 @@ declare class CoreMemoryClient {
      */
     private enrichWithOrgContext;
     /**
-     * Make an HTTP request to the API
+     * Make an HTTP request to the API with retry support
      */
     private request;
+    /**
+     * Validate input using Zod schema and return validation error if invalid
+     */
+    private validateInput;
     /**
      * Test the API connection and authentication
      */
@@ -244,7 +668,7 @@ declare class CoreMemoryClient {
         timestamp: string;
     }>>;
     /**
-     * Create a new memory
+     * Create a new memory with validation
      */
     createMemory(memory: CreateMemoryRequest): Promise<ApiResponse<MemoryEntry>>;
     /**
@@ -252,7 +676,7 @@ declare class CoreMemoryClient {
      */
     getMemory(id: string): Promise<ApiResponse<MemoryEntry>>;
     /**
-     * Update an existing memory
+     * Update an existing memory with validation
      */
     updateMemory(id: string, updates: UpdateMemoryRequest): Promise<ApiResponse<MemoryEntry>>;
     /**
@@ -274,7 +698,7 @@ declare class CoreMemoryClient {
         order?: 'asc' | 'desc';
     }): Promise<ApiResponse<PaginatedResponse<MemoryEntry>>>;
     /**
-     * Search memories using semantic search
+     * Search memories using semantic search with validation
      */
     searchMemories(request: SearchMemoryRequest): Promise<ApiResponse<{
         results: MemorySearchResult[];
@@ -289,7 +713,7 @@ declare class CoreMemoryClient {
         failed_ids: string[];
     }>>;
     /**
-     * Create a new topic
+     * Create a new topic with validation
      */
     createTopic(topic: CreateTopicRequest): Promise<ApiResponse<MemoryTopic>>;
     /**
@@ -312,6 +736,122 @@ declare class CoreMemoryClient {
      * Get user memory statistics
      */
     getMemoryStats(): Promise<ApiResponse<UserMemoryStats>>;
+    /**
+     * 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
+     *   }
+     * });
+     * ```
+     */
+    createMemoryWithPreprocessing(memory: CreateMemoryWithPreprocessingRequest): Promise<ApiResponse<MemoryEntry>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateMemoryWithPreprocessing(id: string, updates: UpdateMemoryWithPreprocessingRequest): Promise<ApiResponse<MemoryEntry>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    enhancedSearch(request: EnhancedSearchRequest): Promise<ApiResponse<EnhancedSearchResponse>>;
+    /**
+     * Get search analytics data
+     *
+     * @example
+     * ```typescript
+     * const analytics = await client.getSearchAnalytics({
+     *   from: '2025-01-01',
+     *   to: '2025-12-31',
+     *   group_by: 'day'
+     * });
+     * ```
+     */
+    getSearchAnalytics(options?: AnalyticsDateRange): Promise<ApiResponse<SearchAnalytics>>;
+    /**
+     * 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);
+     * ```
+     */
+    getAccessPatterns(options?: AnalyticsDateRange): Promise<ApiResponse<AccessPatterns>>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getExtendedStats(): Promise<ApiResponse<ExtendedMemoryStats>>;
+    /**
+     * Get topic with its memories
+     *
+     * @example
+     * ```typescript
+     * const topic = await client.getTopicWithMemories('topic_123');
+     * console.log(topic.data?.memories);
+     * ```
+     */
+    getTopicWithMemories(topicId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        topic: MemoryTopic;
+        memories: MemoryEntry[];
+        total_memories: number;
+        subtopics: Array<{
+            id: string;
+            name: string;
+            memory_count: number;
+        }>;
+    }>>;
+    /**
+     * Get topics in hierarchical structure
+     *
+     * @example
+     * ```typescript
+     * const topics = await client.getTopicsHierarchy();
+     * // Returns nested topic tree with children
+     * ```
+     */
+    getTopicsHierarchy(): Promise<ApiResponse<Array<MemoryTopic & {
+        children: MemoryTopic[];
+        memory_count: number;
+    }>>>;
     /**
      * Update authentication token
      */
@@ -339,54 +879,41 @@ declare class CoreMemoryClient {
 declare function createMemoryClient(config: CoreMemoryClientConfig): CoreMemoryClient;
 
 /**
- * Error handling for Memory Client
+ * Core Utilities for Memory Client
  * Browser-safe, no Node.js dependencies
  */
+
 /**
- * Base error class for Memory Client errors
- */
-declare class MemoryClientError extends Error {
-    code?: string | undefined;
-    statusCode?: number | undefined;
-    details?: unknown | undefined;
-    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: unknown | undefined);
-}
-/**
- * Network/API error
+ * Safe JSON parse result - discriminated union for type-safe error handling
  */
-declare class ApiError extends MemoryClientError {
-    constructor(message: string, statusCode?: number, details?: unknown);
-}
+type SafeJsonResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
 /**
- * Authentication error
+ * Safely parse JSON with detailed error reporting
+ * Prevents scattered try/catch blocks throughout the codebase
  */
-declare class AuthenticationError extends MemoryClientError {
-    constructor(message?: string);
-}
+declare function safeJsonParse<T = unknown>(input: string): SafeJsonResult<T>;
 /**
- * Validation error
+ * HTTP status code to error code mapping
  */
-declare class ValidationError extends MemoryClientError {
-    constructor(message: string, details?: unknown);
-}
+declare function httpStatusToErrorCode(status: number): ErrorCode;
 /**
- * Timeout error
+ * Create a standardized error response from various error sources
  */
-declare class TimeoutError extends MemoryClientError {
-    constructor(message?: string);
-}
+declare function createErrorResponse(message: string, code?: ErrorCode, statusCode?: number, details?: unknown): ApiErrorResponse;
 /**
- * Rate limit error
+ * Calculate retry delay with exponential backoff and jitter
  */
-declare class RateLimitError extends MemoryClientError {
-    constructor(message?: string);
-}
+declare function calculateRetryDelay(attempt: number, baseDelay?: number, backoff?: 'linear' | 'exponential', maxDelay?: number): number;
 /**
- * Not found error
+ * Check if an error is retryable based on status code
  */
-declare class NotFoundError extends MemoryClientError {
-    constructor(resource: string);
-}
+declare function isRetryableError(statusCode?: number): boolean;
 
 /**
  * @lanonasis/memory-client/core
@@ -417,5 +944,5 @@ declare 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 type { ApiError$1 as ApiError, ApiResponse, CoreMemoryClientConfig, CreateMemoryRequest, CreateTopicRequest, MemoryEntry, MemorySearchResult, MemoryStatus, MemoryTopic, MemoryType, PaginatedResponse, SearchMemoryRequest, UpdateMemoryRequest, UserMemoryStats };
+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 };
+export type { AccessPatterns, AnalyticsDateRange, ApiErrorResponse, ApiResponse, ChunkingStrategy, ContentChunk, ContentType, CoreMemoryClientConfig, CreateMemoryRequest, CreateMemoryWithPreprocessingRequest, CreateTopicRequest, EnhancedMemorySearchResult, EnhancedSearchRequest, EnhancedSearchResponse, ErrorCode, ExtendedMemoryStats, HourlyAccess, IntelligentMetadata, MatchingChunk, MemoryEntry, MemoryIntelligence, MemorySearchResult, MemoryStatus, MemoryTopic, MemoryType, MostAccessedMemory, PaginatedResponse, PopularQuery, PreprocessingOptions, ProjectMemoryCount, SafeJsonResult, SearchAnalytics, SearchAnalyticsDataPoint, SearchFilters, SearchMemoryRequest, SearchMode, TagCount, UpdateMemoryRequest, UpdateMemoryWithPreprocessingRequest, UserMemoryStats };