@cmdoss/memwal-sdk 0.6.0

package/src/client/factory.ts

@@ -0,0 +1,155 @@
+/**
+ * Personal Data Wallet Client Factory
+ *
+ * Provides convenience functions for creating PDW-enabled Sui clients
+ * following MystenLabs best practices for client extensions.
+ *
+ * Also includes Simple PDW Client for easy function-based API.
+ */
+
+import { SuiClient } from '@mysten/sui/client';
+import type { PDWConfig } from '../types';
+import { createDefaultConfig, createTestnetConfig } from '../config/defaults';
+import { validateConfig, mergeConfigs } from '../config/validation';
+import { PersonalDataWallet } from './PersonalDataWallet';
+import { SimplePDWClient, type SimplePDWConfig } from './SimplePDWClient';
+import type { Keypair } from '@mysten/sui/cryptography';
+
+/**
+ * Create a new SuiClient extended with Personal Data Wallet functionality
+ * 
+ * @param suiClientConfig - Standard SuiClient configuration
+ * @param pdwConfig - PDW-specific configuration
+ * @returns Extended SuiClient with PDW capabilities
+ * 
+ * @example
+ * ```typescript
+ * const client = createPDWClient(
+ *   { url: 'https://fullnode.devnet.sui.io' },
+ *   {
+ *     packageId: '0x123...'
+ *   }
+ * );
+ * 
+ * // Now use PDW functionality
+ * const memory = await client.pdw.createMemory({
+ *   content: 'My first memory',
+ *   category: 'personal',
+ *   userAddress: '0x789...'
+ * });
+ * ```
+ */
+export function createPDWClient(
+  suiClientConfig: ConstructorParameters<typeof SuiClient>[0],
+  pdwConfig?: Partial<PDWConfig>
+) {
+  const suiClient = new SuiClient(suiClientConfig);
+  const fullConfig = validateConfig(mergeConfigs(createDefaultConfig(), pdwConfig || {}));
+  
+  return suiClient.$extend(PersonalDataWallet.asClientExtension(pdwConfig));
+}
+
+/**
+ * Extend an existing SuiClient with Personal Data Wallet functionality
+ * 
+ * @param client - Existing SuiClient instance
+ * @param pdwConfig - PDW-specific configuration
+ * @returns Extended client with PDW capabilities
+ */
+export function extendWithPDW(
+  client: SuiClient,
+  pdwConfig?: Partial<PDWConfig>
+) {
+  return client.$extend(PersonalDataWallet.asClientExtension(pdwConfig));
+}
+
+/**
+ * Create a PDW client with common development settings
+ * 
+ * @param overrides - Any configuration overrides
+ * @returns Development-ready PDW client
+ */
+export function createDevPDWClient(overrides?: {
+  suiUrl?: string;
+  packageId?: string;
+}) {
+  return createPDWClient(
+    {
+      url: overrides?.suiUrl || 'https://fullnode.devnet.sui.io',
+    },
+    {
+      packageId: overrides?.packageId || '0x0',
+      encryptionConfig: {
+        enabled: true,
+        keyServers: ['0x0'], // Placeholder for development
+        policyConfig: {
+          threshold: 2,
+        },
+      },
+      storageConfig: {
+        provider: 'walrus',
+        cacheEnabled: true,
+        encryptionEnabled: true,
+      },
+    }
+  );
+}
+
+/**
+ * Create a PDW client configured for testnet
+ * 
+ * @param overrides - Any configuration overrides
+ * @returns Testnet-ready PDW client
+ */
+export function createTestnetPDWClient(overrides?: Partial<PDWConfig>) {
+  const testnetConfig = createTestnetConfig(overrides);
+
+  return createPDWClient(
+    { url: 'https://fullnode.testnet.sui.io' },
+    testnetConfig
+  );
+}
+
+// ==================== SIMPLE PDW CLIENT ====================
+
+/**
+ * Create a Simple PDW Client (function-based API, no hooks)
+ *
+ * @param config - Simple client configuration
+ * @returns Initialized simple client
+ *
+ * @example
+ * ```typescript
+ * import { createSimplePDWClient } from 'personal-data-wallet-sdk';
+ *
+ * const pdw = await createSimplePDWClient({
+ *   signer: keypair,
+ *   network: 'testnet',
+ *   geminiApiKey: process.env.GEMINI_API_KEY
+ * });
+ *
+ * await pdw.memory.create('I love TypeScript');
+ * const results = await pdw.search.vector('programming');
+ * ```
+ */
+export async function createSimplePDWClient(config: SimplePDWConfig): Promise<SimplePDWClient> {
+  const client = new SimplePDWClient(config);
+  await client.ready();
+  return client;
+}
+
+/**
+ * Create Simple PDW Client from Keypair
+ *
+ * Helper for Node.js environments
+ */
+export async function createSimplePDWClientFromKeypair(
+  keypair: Keypair,
+  config: Omit<SimplePDWConfig, 'signer' | 'userAddress'>
+): Promise<SimplePDWClient> {
+  return createSimplePDWClient({
+    ...config,
+    signer: keypair,
+    userAddress: keypair.getPublicKey().toSuiAddress()
+  });
+}

package/src/client/namespaces/AnalyticsNamespace.ts

@@ -0,0 +1,377 @@
+/**
+ * Analytics Namespace - Memory Analytics & Insights
+ *
+ * Pure delegation to MemoryAnalyticsService for comprehensive analytics.
+ * Provides insights, trends, clustering, and recommendations.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+import type {
+  MemoryAnalytics,
+  UsagePattern,
+  SimilarityCluster,
+  MemoryInsights
+} from '../../retrieval/MemoryAnalyticsService';
+
+/**
+ * Analytics options
+ */
+export interface AnalyticsOptions {
+  periodStart?: Date;
+  periodEnd?: Date;
+  includeForecasting?: boolean;
+  includeClustering?: boolean;
+  includeInsights?: boolean;
+}
+
+/**
+ * Category distribution
+ */
+export interface CategoryDistribution {
+  category: string;
+  count: number;
+  percentage: number;
+}
+
+/**
+ * Trend data
+ */
+export interface TrendData {
+  direction: 'up' | 'down' | 'stable' | 'volatile';
+  strength: number;
+  forecast?: Array<{ date: Date; predicted: number; confidence: number }>;
+}
+
+/**
+ * Analytics Namespace
+ *
+ * Handles memory analytics, insights, and visualization data
+ */
+export class AnalyticsNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Generate comprehensive analytics report
+   *
+   * Delegates to: MemoryAnalyticsService.generateMemoryAnalytics()
+   *
+   * @param options - Analytics options
+   * @returns Complete analytics report
+   */
+  async generate(options?: AnalyticsOptions): Promise<MemoryAnalytics> {
+    if (!this.services.analytics) {
+      throw new Error('Analytics service not configured.');
+    }
+
+    // Get user's memories first
+    const memoriesResult = await this.services.viewService?.getUserMemories(
+      this.services.config.userAddress
+    );
+
+    const memories = memoriesResult?.data || [];
+
+    // Convert to UnifiedMemoryResult format
+    const unifiedMemories = memories.map((m: any) => ({
+      id: m.id,
+      category: m.category,
+      created: new Date(m.createdAt || Date.now()),
+      metadata: {
+        size: 0,
+        importance: m.importance || 5,
+        contentType: 'text',
+        tags: m.tags || []
+      },
+      analytics: {
+        viewCount: 0
+      }
+    }));
+
+    return await this.services.analytics.generateMemoryAnalytics(
+      this.services.config.userAddress,
+      unifiedMemories as any,
+      options
+    );
+  }
+
+  /**
+   * Get category distribution
+   *
+   * Delegates to: MemoryAnalyticsService.generateMemoryAnalytics() → topCategories
+   *
+   * @returns Category distribution data
+   */
+  async categories(): Promise<CategoryDistribution[]> {
+    const analytics = await this.generate({ includeInsights: false, includeClustering: false });
+    return analytics.topCategories;
+  }
+
+  /**
+   * Get temporal trends
+   *
+   * Delegates to: MemoryAnalyticsService.generateMemoryAnalytics() → temporalTrends
+   *
+   * @returns Trend analysis data
+   */
+  async trends(): Promise<{
+    creation: TrendData;
+    access: TrendData;
+    size: TrendData;
+  }> {
+    const analytics = await this.generate({ includeForecasting: true });
+
+    return {
+      creation: {
+        direction: analytics.temporalTrends.creationTrend.direction,
+        strength: analytics.temporalTrends.creationTrend.strength,
+        forecast: analytics.temporalTrends.creationTrend.forecast
+      },
+      access: {
+        direction: analytics.temporalTrends.accessTrend.direction,
+        strength: analytics.temporalTrends.accessTrend.strength,
+        forecast: analytics.temporalTrends.accessTrend.forecast
+      },
+      size: {
+        direction: analytics.temporalTrends.sizeTrend.direction,
+        strength: analytics.temporalTrends.sizeTrend.strength,
+        forecast: analytics.temporalTrends.sizeTrend.forecast
+      }
+    };
+  }
+
+  /**
+   * Get importance distribution
+   *
+   * Analyzes how memories are distributed by importance level
+   *
+   * @returns Importance analysis
+   */
+  async importance(): Promise<{
+    average: number;
+    distribution: Record<number, number>;
+    highImportance: number;
+    lowImportance: number;
+  }> {
+    const analytics = await this.generate({ includeInsights: false });
+
+    // Calculate distribution from memories
+    const memoriesResult = await this.services.viewService?.getUserMemories(
+      this.services.config.userAddress
+    );
+
+    const memories = memoriesResult?.data || [];
+
+    const distribution: Record<number, number> = {};
+    let highCount = 0;
+    let lowCount = 0;
+
+    memories.forEach((m: any) => {
+      const imp = m.importance || 5;
+      distribution[imp] = (distribution[imp] || 0) + 1;
+
+      if (imp >= 8) highCount++;
+      if (imp <= 3) lowCount++;
+    });
+
+    return {
+      average: analytics.averageImportance,
+      distribution,
+      highImportance: highCount,
+      lowImportance: lowCount
+    };
+  }
+
+  /**
+   * Get temporal patterns
+   *
+   * Delegates to: MemoryAnalyticsService.analyzeUsagePatterns()
+   *
+   * @returns Usage patterns by time
+   */
+  async temporal(): Promise<UsagePattern[]> {
+    const analytics = await this.generate({ includeInsights: false });
+    return analytics.usagePatterns;
+  }
+
+  /**
+   * Get AI-generated insights
+   *
+   * Delegates to: MemoryAnalyticsService.generateKnowledgeInsights()
+   *
+   * @returns Knowledge insights and recommendations
+   */
+  async insights(): Promise<MemoryInsights> {
+    const analytics = await this.generate({ includeInsights: true });
+    return analytics.knowledgeInsights;
+  }
+
+  /**
+   * Detect anomalies in memory patterns
+   *
+   * Finds unusual patterns or outliers
+   *
+   * @returns Array of detected anomalies
+   */
+  async anomalies(): Promise<Array<{
+    date: Date;
+    type: 'spike' | 'drop' | 'outlier';
+    severity: number;
+    description: string;
+  }>> {
+    const analytics = await this.generate();
+
+    // Extract anomalies from usage patterns
+    const anomalies: Array<{
+      date: Date;
+      type: 'spike' | 'drop' | 'outlier';
+      severity: number;
+      description: string;
+    }> = [];
+
+    analytics.usagePatterns.forEach(pattern => {
+      pattern.anomalies.forEach(anomaly => {
+        anomalies.push({
+          date: anomaly.date,
+          type: anomaly.type,
+          severity: anomaly.severity,
+          description: anomaly.possibleCauses?.join(', ') || 'Unknown cause'
+        });
+      });
+    });
+
+    return anomalies;
+  }
+
+  /**
+   * Analyze correlations between categories/topics
+   *
+   * Finds relationships between different memory types
+   *
+   * @returns Correlation data
+   */
+  async correlations(): Promise<Array<{
+    concept1: string;
+    concept2: string;
+    strength: number;
+    memoryCount: number;
+  }>> {
+    const analytics = await this.generate({ includeInsights: true });
+
+    // Extract from conceptual connections
+    return analytics.knowledgeInsights.conceptualConnections.map(conn => ({
+      concept1: conn.concept1,
+      concept2: conn.concept2,
+      strength: conn.connectionStrength,
+      memoryCount: conn.bridgeMemories.length
+    }));
+  }
+
+  /**
+   * Analyze a single memory
+   *
+   * Get detailed analytics for one memory
+   *
+   * @param memoryId - Memory ID to analyze
+   * @returns Memory-specific analytics
+   */
+  async analyze(memoryId: string): Promise<{
+    memoryId: string;
+    importance: number;
+    category: string;
+    relatedCount: number;
+    clusterInfo?: {
+      clusterId: string;
+      similarity: number;
+    };
+  }> {
+    // Get memory details
+    const memory = await this.services.storage.retrieveMemoryPackage(memoryId);
+
+    // Decode content if it's Uint8Array
+    const content = typeof memory.content === 'string'
+      ? memory.content
+      : new TextDecoder().decode(memory.content);
+
+    // Related memories search requires vector service
+    // For now return basic analysis without related count
+    return {
+      memoryId,
+      importance: memory.metadata.importance || 5,
+      category: memory.metadata.category,
+      relatedCount: 0, // Would require vector search
+      clusterInfo: undefined // Would require full clustering analysis
+    };
+  }
+
+  /**
+   * Get visualization-ready data
+   *
+   * Formats analytics for charts and graphs
+   *
+   * @returns Chart-ready data
+   */
+  async visualizationData(): Promise<{
+    categoryChart: Array<{ name: string; value: number }>;
+    importanceChart: Array<{ level: number; count: number }>;
+    timelineChart: Array<{ date: string; count: number }>;
+    clusterChart: Array<{ id: string; size: number; coherence: number }>;
+  }> {
+    const analytics = await this.generate({ includeClustering: true });
+
+    // Category chart data
+    const categoryChart = analytics.topCategories.map(c => ({
+      name: c.category,
+      value: c.count
+    }));
+
+    // Importance chart data
+    const importanceData = await this.importance();
+    const importanceChart = Object.entries(importanceData.distribution).map(([level, count]) => ({
+      level: parseInt(level),
+      count
+    }));
+
+    // Timeline chart data - aggregate memories by date
+    const timelineChart: Array<{ date: string; count: number }> = [];
+    try {
+      const memoriesResult = await this.services.viewService?.getUserMemories(
+        this.services.config.userAddress,
+        { limit: 1000 }
+      );
+      const memories = memoriesResult?.data || [];
+
+      // Group memories by date (YYYY-MM-DD)
+      const dateCountMap = new Map<string, number>();
+      memories.forEach((m: any) => {
+        const timestamp = m.createdAt || m.updatedAt || Date.now();
+        const dateStr = new Date(timestamp).toISOString().split('T')[0];
+        dateCountMap.set(dateStr, (dateCountMap.get(dateStr) || 0) + 1);
+      });
+
+      // Sort by date and convert to array
+      const sortedDates = Array.from(dateCountMap.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]));
+
+      sortedDates.forEach(([date, count]) => {
+        timelineChart.push({ date, count });
+      });
+    } catch (error) {
+      console.warn('Failed to generate timeline chart data:', error);
+    }
+
+    // Cluster chart data
+    const clusterChart = analytics.similarityClusters.map(c => ({
+      id: c.id,
+      size: c.size,
+      coherence: c.coherence
+    }));
+
+    return {
+      categoryChart,
+      importanceChart,
+      timelineChart,
+      clusterChart
+    };
+  }
+}