@lanonasis/memory-client 1.0.1 → 2.1.0

package/dist/node/index.d.ts

@@ -0,0 +1,329 @@
+import { ApiResponse, PaginatedResponse, CoreMemoryClientConfig } from '../core/client';
+export { ApiResponse, PaginatedResponse } from '../core/client';
+import { MemoryEntry, MemorySearchResult, CreateMemoryRequest, SearchMemoryRequest, UpdateMemoryRequest, CreateTopicRequest, MemoryTopic, UserMemoryStats } from '../core/types';
+export { CreateMemoryRequest, CreateTopicRequest, MemoryEntry, MemorySearchResult, MemoryStatus, MemoryTopic, MemoryType, SearchMemoryRequest, UpdateMemoryRequest, UserMemoryStats } from '../core/types';
+
+/**
+ * CLI Integration Module for Memory Client SDK
+ *
+ * Provides intelligent CLI detection and MCP channel utilization
+ * when @lanonasis/cli v1.5.2+ is available in the environment
+ *
+ * IMPORTANT: This file imports Node.js modules and should only be used in Node.js environments
+ */
+
+interface CLIInfo {
+    available: boolean;
+    version?: string;
+    mcpAvailable?: boolean;
+    authenticated?: boolean;
+}
+interface CLIExecutionOptions {
+    timeout?: number;
+    verbose?: boolean;
+    outputFormat?: 'json' | 'table' | 'yaml';
+}
+interface CLICommand {
+    command: string;
+    args: string[];
+    options?: CLIExecutionOptions;
+}
+interface MCPChannel {
+    available: boolean;
+    version?: string;
+    capabilities?: string[];
+}
+interface CLICapabilities {
+    cliAvailable: boolean;
+    mcpSupport: boolean;
+    authenticated: boolean;
+    goldenContract: boolean;
+    version?: string;
+}
+type RoutingStrategy = 'cli-first' | 'api-first' | 'cli-only' | 'api-only' | 'auto';
+interface CLIAuthStatus {
+    authenticated: boolean;
+    user?: {
+        id?: string;
+        email?: string;
+        name?: string;
+        [key: string]: unknown;
+    };
+    scopes?: string[];
+    expiresAt?: string;
+    [key: string]: unknown;
+}
+interface CLIMCPStatus {
+    connected: boolean;
+    channel?: string;
+    endpoint?: string;
+    details?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface CLIMCPTool {
+    name: string;
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * CLI Detection and Integration Service
+ */
+declare class CLIIntegration {
+    private cliInfo;
+    private detectionPromise;
+    /**
+     * Detect if CLI is available and get its capabilities
+     */
+    detectCLI(): Promise<CLIInfo>;
+    private performDetection;
+    /**
+     * Execute CLI command and return parsed JSON result
+     */
+    executeCLICommand<T = unknown>(command: string, options?: CLIExecutionOptions): Promise<ApiResponse<T>>;
+    /**
+     * Get preferred CLI command (onasis for Golden Contract, fallback to lanonasis)
+     */
+    private getPreferredCLICommand;
+    /**
+     * Memory operations via CLI
+     */
+    createMemoryViaCLI(title: string, content: string, options?: {
+        memoryType?: string;
+        tags?: string[];
+        topicId?: string;
+    }): Promise<ApiResponse<MemoryEntry>>;
+    listMemoriesViaCLI(options?: {
+        limit?: number;
+        memoryType?: string;
+        tags?: string[];
+        sortBy?: string;
+    }): Promise<ApiResponse<PaginatedResponse<MemoryEntry>>>;
+    searchMemoriesViaCLI(query: string, options?: {
+        limit?: number;
+        memoryTypes?: string[];
+    }): Promise<ApiResponse<{
+        results: MemorySearchResult[];
+        total_results: number;
+        search_time_ms: number;
+    }>>;
+    /**
+     * Health check via CLI
+     */
+    healthCheckViaCLI(): Promise<ApiResponse<{
+        status: string;
+        timestamp: string;
+    }>>;
+    /**
+     * MCP-specific operations
+     */
+    getMCPStatus(): Promise<ApiResponse<CLIMCPStatus>>;
+    listMCPTools(): Promise<ApiResponse<{
+        tools: CLIMCPTool[];
+    }>>;
+    /**
+     * Authentication operations
+     */
+    getAuthStatus(): Promise<ApiResponse<CLIAuthStatus>>;
+    /**
+     * Check if specific CLI features are available
+     */
+    getCapabilities(): Promise<{
+        cliAvailable: boolean;
+        version?: string;
+        mcpSupport: boolean;
+        authenticated: boolean;
+        goldenContract: boolean;
+    }>;
+    private isGoldenContractCompliant;
+    /**
+     * Force refresh CLI detection
+     */
+    refresh(): Promise<CLIInfo>;
+    /**
+     * Get cached CLI info without re-detection
+     */
+    getCachedInfo(): CLIInfo | null;
+}
+declare const cliIntegration: CLIIntegration;
+
+/**
+ * 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;
+}
+
+/**
+ * Enhanced Memory Client with CLI Integration
+ *
+ * Intelligently routes requests through CLI v1.5.2+ when available,
+ * with fallback to direct API for maximum compatibility and performance
+ *
+ * IMPORTANT: This file uses Node.js-specific features (process.env) and should only be used in Node.js environments
+ */
+
+interface EnhancedMemoryClientConfig extends CoreMemoryClientConfig {
+    /** Prefer CLI when available (default: true) */
+    preferCLI?: boolean;
+    /** Enable MCP channels when available (default: true) */
+    enableMCP?: boolean;
+    /** CLI detection timeout in ms (default: 5000) */
+    cliDetectionTimeout?: number;
+    /** Fallback to direct API on CLI failure (default: true) */
+    fallbackToAPI?: boolean;
+    /** Minimum CLI version required for Golden Contract compliance (default: 1.5.2) */
+    minCLIVersion?: string;
+    /** Enable verbose logging for troubleshooting (default: false) */
+    verbose?: boolean;
+}
+interface OperationResult<T> {
+    data?: T;
+    error?: ApiErrorResponse;
+    source: 'cli' | 'api';
+    mcpUsed?: boolean;
+}
+/**
+ * Enhanced Memory Client with intelligent CLI/API routing
+ */
+declare class EnhancedMemoryClient {
+    private directClient;
+    private cliIntegration;
+    private config;
+    private capabilities;
+    private createDefaultCapabilities;
+    constructor(config: EnhancedMemoryClientConfig);
+    /**
+     * Initialize the client and detect capabilities
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get current capabilities
+     */
+    getCapabilities(): Promise<Awaited<ReturnType<CLIIntegration['getCapabilities']>>>;
+    /**
+     * Determine if operation should use CLI
+     */
+    private shouldUseCLI;
+    /**
+     * Execute operation with intelligent routing
+     */
+    private executeOperation;
+    /**
+     * Health check with intelligent routing
+     */
+    healthCheck(): Promise<OperationResult<{
+        status: string;
+        timestamp: string;
+    }>>;
+    /**
+     * Create memory with CLI/API routing
+     */
+    createMemory(memory: CreateMemoryRequest): Promise<OperationResult<MemoryEntry>>;
+    /**
+     * List memories with intelligent routing
+     */
+    listMemories(options?: {
+        page?: number;
+        limit?: number;
+        memory_type?: string;
+        topic_id?: string;
+        project_ref?: string;
+        status?: string;
+        tags?: string[];
+        sort?: string;
+        order?: 'asc' | 'desc';
+    }): Promise<OperationResult<PaginatedResponse<MemoryEntry>>>;
+    /**
+     * Search memories with MCP enhancement when available
+     */
+    searchMemories(request: SearchMemoryRequest): Promise<OperationResult<{
+        results: MemorySearchResult[];
+        total_results: number;
+        search_time_ms: number;
+    }>>;
+    /**
+     * Get memory by ID (API only for now)
+     */
+    getMemory(id: string): Promise<OperationResult<MemoryEntry>>;
+    /**
+     * Update memory (API only for now)
+     */
+    updateMemory(id: string, updates: UpdateMemoryRequest): Promise<OperationResult<MemoryEntry>>;
+    /**
+     * Delete memory (API only for now)
+     */
+    deleteMemory(id: string): Promise<OperationResult<void>>;
+    createTopic(topic: CreateTopicRequest): Promise<OperationResult<MemoryTopic>>;
+    getTopics(): Promise<OperationResult<MemoryTopic[]>>;
+    getTopic(id: string): Promise<OperationResult<MemoryTopic>>;
+    updateTopic(id: string, updates: Partial<CreateTopicRequest>): Promise<OperationResult<MemoryTopic>>;
+    deleteTopic(id: string): Promise<OperationResult<void>>;
+    /**
+     * Get memory statistics
+     */
+    getMemoryStats(): Promise<OperationResult<UserMemoryStats>>;
+    /**
+     * Force CLI re-detection
+     */
+    refreshCLIDetection(): Promise<void>;
+    /**
+     * Get authentication status from CLI
+     */
+    getAuthStatus(): Promise<OperationResult<CLIAuthStatus>>;
+    /**
+     * Get MCP status when available
+     */
+    getMCPStatus(): Promise<OperationResult<CLIMCPStatus>>;
+    /**
+     * Update authentication for both CLI and API client
+     */
+    setAuthToken(token: string): void;
+    setApiKey(apiKey: string): void;
+    clearAuth(): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(updates: Partial<EnhancedMemoryClientConfig>): void;
+    /**
+     * Get configuration summary
+     */
+    getConfigSummary(): {
+        apiUrl: string;
+        preferCLI: boolean;
+        enableMCP: boolean;
+        capabilities?: Awaited<ReturnType<CLIIntegration['getCapabilities']>>;
+    };
+}
+/**
+ * Factory function to create an enhanced memory client
+ */
+declare function createNodeMemoryClient(config: EnhancedMemoryClientConfig): Promise<EnhancedMemoryClient>;
+/**
+ * Synchronous factory function (initialization happens on first API call)
+ */
+declare function createEnhancedMemoryClient(config: EnhancedMemoryClientConfig): EnhancedMemoryClient;
+
+export { CLIIntegration, EnhancedMemoryClient, cliIntegration, createEnhancedMemoryClient, createNodeMemoryClient };
+export type { ApiErrorResponse, CLIAuthStatus, CLICapabilities, CLICommand, CLIExecutionOptions, CLIInfo, CLIMCPStatus, CLIMCPTool, EnhancedMemoryClientConfig, ErrorCode, MCPChannel, OperationResult, RoutingStrategy };