@memorylayerai/sdk 0.1.0 → 0.2.0

package/src/resources/graph.ts

@@ -0,0 +1,212 @@
+import { HTTPClient } from '../http-client.js';
+import {
+  GraphData,
+  NodeDetails,
+  GetGraphRequest,
+  GetNodeDetailsRequest,
+  GetNodeEdgesRequest,
+  GetNodeEdgesResponse,
+} from '../types.js';
+import { ValidationError } from '../errors.js';
+
+/**
+ * Resource for graph visualization operations
+ * 
+ * Provides methods to fetch graph data (nodes and edges) for visualization.
+ * 
+ * Requirements: 6.1, 6.2, 6.3, 6.4
+ */
+export class GraphResource {
+  constructor(private httpClient: HTTPClient) {}
+
+  /**
+   * Get graph data for a space/project
+   * 
+   * Fetches nodes (memories, documents, entities) and edges (relationships)
+   * for visualization. Supports pagination and filtering.
+   * 
+   * @param request - Graph data request with filters
+   * @returns Graph data with nodes, edges, metadata, and pagination
+   * 
+   * @example
+   * ```typescript
+   * const graphData = await client.graph.getGraph({
+   *   spaceId: 'project-123',
+   *   limit: 100,
+   *   nodeTypes: ['memory', 'document'],
+   *   relationshipTypes: ['extends', 'updates']
+   * });
+   * 
+   * console.log(`Found ${graphData.nodes.length} nodes`);
+   * console.log(`Found ${graphData.edges.length} edges`);
+   * ```
+   * 
+   * Requirements: 6.1
+   */
+  async getGraph(request: GetGraphRequest): Promise<GraphData> {
+    // Validate request
+    if (!request.spaceId || request.spaceId.trim().length === 0) {
+      throw new ValidationError(
+        'Space ID is required',
+        [{ field: 'spaceId', message: 'Space ID is required' }]
+      );
+    }
+
+    // Build query parameters
+    const query: Record<string, string> = {};
+
+    if (request.cursor) {
+      query.cursor = request.cursor;
+    }
+
+    if (request.limit !== undefined) {
+      query.limit = request.limit.toString();
+    }
+
+    if (request.nodeTypes && request.nodeTypes.length > 0) {
+      query.nodeTypes = request.nodeTypes.join(',');
+    }
+
+    if (request.relationshipTypes && request.relationshipTypes.length > 0) {
+      query.relationshipTypes = request.relationshipTypes.join(',');
+    }
+
+    if (request.startDate) {
+      query.startDate = request.startDate;
+    }
+
+    if (request.endDate) {
+      query.endDate = request.endDate;
+    }
+
+    return this.httpClient.request<GraphData>({
+      method: 'GET',
+      path: `/v1/graph/spaces/${request.spaceId}`,
+      query,
+    });
+  }
+
+  /**
+   * Get detailed information for a specific node
+   * 
+   * Fetches node data, connected edges, and neighboring nodes.
+   * 
+   * @param request - Node details request
+   * @returns Node details with edges and connected nodes
+   * 
+   * @example
+   * ```typescript
+   * const details = await client.graph.getNodeDetails({
+   *   nodeId: 'memory-456'
+   * });
+   * 
+   * console.log(`Node: ${details.node.label}`);
+   * console.log(`Connected to ${details.connectedNodes.length} nodes`);
+   * ```
+   * 
+   * Requirements: 6.2
+   */
+  async getNodeDetails(request: GetNodeDetailsRequest): Promise<NodeDetails> {
+    // Validate request
+    if (!request.nodeId || request.nodeId.trim().length === 0) {
+      throw new ValidationError(
+        'Node ID is required',
+        [{ field: 'nodeId', message: 'Node ID is required' }]
+      );
+    }
+
+    return this.httpClient.request<NodeDetails>({
+      method: 'GET',
+      path: `/v1/graph/nodes/${request.nodeId}`,
+    });
+  }
+
+  /**
+   * Get edges connected to a specific node
+   * 
+   * Fetches edges and connected nodes, optionally filtered by edge type.
+   * 
+   * @param request - Node edges request
+   * @returns Edges and connected nodes
+   * 
+   * @example
+   * ```typescript
+   * const edges = await client.graph.getNodeEdges({
+   *   nodeId: 'memory-456',
+   *   edgeTypes: ['extends', 'updates']
+   * });
+   * 
+   * console.log(`Found ${edges.edges.length} edges`);
+   * ```
+   * 
+   * Requirements: 6.3
+   */
+  async getNodeEdges(request: GetNodeEdgesRequest): Promise<GetNodeEdgesResponse> {
+    // Validate request
+    if (!request.nodeId || request.nodeId.trim().length === 0) {
+      throw new ValidationError(
+        'Node ID is required',
+        [{ field: 'nodeId', message: 'Node ID is required' }]
+      );
+    }
+
+    // Build query parameters
+    const query: Record<string, string> = {};
+
+    if (request.edgeTypes && request.edgeTypes.length > 0) {
+      query.edgeTypes = request.edgeTypes.join(',');
+    }
+
+    return this.httpClient.request<GetNodeEdgesResponse>({
+      method: 'GET',
+      path: `/v1/graph/nodes/${request.nodeId}/edges`,
+      query,
+    });
+  }
+
+  /**
+   * Get all graph pages using async iteration
+   * 
+   * Automatically handles pagination to fetch all nodes and edges.
+   * Yields each page of results as they are fetched.
+   * 
+   * @param request - Initial graph request (without cursor)
+   * @yields Graph data for each page
+   * 
+   * @example
+   * ```typescript
+   * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+   *   console.log(`Page has ${page.nodes.length} nodes`);
+   *   // Process nodes...
+   * }
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Collect all nodes
+   * const allNodes: GraphNode[] = [];
+   * for await (const page of client.graph.getAllGraphPages({ spaceId: 'project-123' })) {
+   *   allNodes.push(...page.nodes);
+   * }
+   * console.log(`Total nodes: ${allNodes.length}`);
+   * ```
+   * 
+   * Requirements: 6.4
+   */
+  async *getAllGraphPages(request: Omit<GetGraphRequest, 'cursor'>): AsyncGenerator<GraphData, void, undefined> {
+    let cursor: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const page = await this.getGraph({
+        ...request,
+        cursor,
+      });
+
+      yield page;
+
+      cursor = page.pagination.nextCursor;
+      hasMore = page.pagination.hasMore;
+    }
+  }
+}

package/src/types.ts

@@ -223,3 +223,182 @@ export interface StreamChunk {
   /** Array of streaming choices */
   choices: StreamChoice[];
 }
+
+// ============================================================================
+// Graph Visualization Types
+// ============================================================================
+
+/**
+ * Memory status for visualization
+ */
+export type MemoryStatus = 'latest' | 'older' | 'forgotten' | 'expiring' | 'new';
+
+/**
+ * Node types in the graph
+ */
+export type NodeType = 'memory' | 'document' | 'entity';
+
+/**
+ * Edge types in the graph
+ */
+export type EdgeType = 'updates' | 'extends' | 'derives' | 'similarity';
+
+/**
+ * Node in the graph (memory, document, or entity)
+ */
+export interface GraphNode {
+  /** Unique identifier for the node */
+  id: string;
+  /** Type of node */
+  type: NodeType;
+  /** Display label (truncated content or title) */
+  label: string;
+  /** Node data */
+  data: {
+    /** Full content (for memory nodes) */
+    content?: string;
+    /** Title (for document nodes) */
+    title?: string;
+    /** Memory status */
+    status?: MemoryStatus;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Expiration timestamp (ISO 8601) */
+    expiresAt?: string;
+    /** Source reference */
+    source?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+  };
+  /** Optional position hints for layout */
+  position?: { x: number; y: number };
+}
+
+/**
+ * Edge in the graph (relationship or similarity)
+ */
+export interface GraphEdge {
+  /** Unique identifier for the edge */
+  id: string;
+  /** Source node ID */
+  source: string;
+  /** Target node ID */
+  target: string;
+  /** Type of edge */
+  type: EdgeType;
+  /** Display label for the edge */
+  label?: string;
+  /** Edge data */
+  data: {
+    /** Strength of the relationship (0.0 to 1.0) */
+    strength: number;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+  };
+}
+
+/**
+ * Graph metadata and statistics
+ */
+export interface GraphMetadata {
+  /** Total number of nodes */
+  totalNodes: number;
+  /** Number of memory nodes */
+  memoryCount: number;
+  /** Number of document nodes */
+  documentCount: number;
+  /** Number of entity nodes */
+  entityCount: number;
+  /** Total number of edges */
+  totalEdges: number;
+  /** Number of relationship edges */
+  relationshipCount: number;
+  /** Number of similarity edges */
+  similarityCount: number;
+}
+
+/**
+ * Pagination information
+ */
+export interface PaginationInfo {
+  /** Whether there are more results */
+  hasMore: boolean;
+  /** Cursor for the next page */
+  nextCursor?: string;
+  /** Total count (optional, may be expensive to compute) */
+  totalCount?: number;
+}
+
+/**
+ * Complete graph data structure
+ */
+export interface GraphData {
+  /** Array of nodes */
+  nodes: GraphNode[];
+  /** Array of edges */
+  edges: GraphEdge[];
+  /** Graph metadata and statistics */
+  metadata: GraphMetadata;
+  /** Pagination information */
+  pagination: PaginationInfo;
+}
+
+/**
+ * Request to get graph data
+ */
+export interface GetGraphRequest {
+  /** Space/project ID to fetch graph for */
+  spaceId: string;
+  /** Pagination cursor (optional) */
+  cursor?: string;
+  /** Maximum number of nodes to return (default: 500, max: 2000) */
+  limit?: number;
+  /** Filter by node types */
+  nodeTypes?: NodeType[];
+  /** Filter by relationship types */
+  relationshipTypes?: EdgeType[];
+  /** Filter by start date (ISO 8601) */
+  startDate?: string;
+  /** Filter by end date (ISO 8601) */
+  endDate?: string;
+}
+
+/**
+ * Node details response
+ */
+export interface NodeDetails {
+  /** The node */
+  node: GraphNode;
+  /** Edges connected to this node */
+  edges: GraphEdge[];
+  /** Neighboring nodes */
+  connectedNodes: GraphNode[];
+}
+
+/**
+ * Request to get node details
+ */
+export interface GetNodeDetailsRequest {
+  /** Node ID */
+  nodeId: string;
+}
+
+/**
+ * Request to get node edges
+ */
+export interface GetNodeEdgesRequest {
+  /** Node ID */
+  nodeId: string;
+  /** Filter by edge types (optional) */
+  edgeTypes?: EdgeType[];
+}
+
+/**
+ * Response for get node edges
+ */
+export interface GetNodeEdgesResponse {
+  /** Edges connected to the node */
+  edges: GraphEdge[];
+  /** Nodes connected via these edges */
+  connectedNodes: GraphNode[];
+}

package/tests/graph.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { MemoryLayerClient } from '../src/index.js';
+import type { GraphData, GraphNode } from '../src/types.js';
+
+/**
+ * Graph SDK Tests
+ * 
+ * These tests verify the Node.js SDK graph methods work correctly.
+ * 
+ * NOTE: These tests require a running backend with test data.
+ * They are integration tests, not unit tests.
+ * 
+ * Requirements: 6.1, 6.2, 6.3, 6.4
+ */
+
+describe('Graph SDK Tests', () => {
+  let client: MemoryLayerClient;
+  const testSpaceId = process.env.TEST_SPACE_ID || 'test-space-123';
+
+  beforeAll(() => {
+    const apiKey = process.env.MEMORYLAYER_API_KEY || process.env.TEST_API_KEY;
+    
+    if (!apiKey) {
+      throw new Error('API key required for tests. Set MEMORYLAYER_API_KEY or TEST_API_KEY environment variable.');
+    }
+
+    client = new MemoryLayerClient({
+      apiKey,
+      baseURL: process.env.TEST_BASE_URL || 'http://localhost:3001',
+    });
+  });
+
+  describe('getGraph', () => {
+    it('should fetch graph data for a space', async () => {
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        limit: 10,
+      });
+
+      expect(graphData).toBeDefined();
+      expect(Array.isArray(graphData.nodes)).toBe(true);
+      expect(Array.isArray(graphData.edges)).toBe(true);
+      expect(graphData.metadata).toBeDefined();
+      expect(graphData.pagination).toBeDefined();
+    });
+
+    it('should support node type filtering', async () => {
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        nodeTypes: ['memory'],
+        limit: 10,
+      });
+
+      expect(graphData.nodes.every((n: GraphNode) => n.type === 'memory')).toBe(true);
+    });
+
+    it('should support relationship type filtering', async () => {
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        relationshipTypes: ['extends', 'updates'],
+        limit: 10,
+      });
+
+      expect(graphData.edges.every((e: import('../src/types.js').GraphEdge) => 
+        ['extends', 'updates'].includes(e.type)
+      )).toBe(true);
+    });
+
+    it('should support date range filtering', async () => {
+      const startDate = '2026-01-01T00:00:00Z';
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        startDate,
+        limit: 10,
+      });
+
+      expect(graphData.nodes.every((n: GraphNode) => 
+        new Date(n.data.createdAt) >= new Date(startDate)
+      )).toBe(true);
+    });
+
+    it('should throw validation error for missing spaceId', async () => {
+      await expect(
+        client.graph.getGraph({ spaceId: '' })
+      ).rejects.toThrow('Space ID is required');
+    });
+  });
+
+  describe('getNodeDetails', () => {
+    it('should fetch node details', async () => {
+      // First get a node ID
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        limit: 1,
+      });
+
+      if (graphData.nodes.length === 0) {
+        console.warn('No nodes available for testing getNodeDetails');
+        return;
+      }
+
+      const nodeId = graphData.nodes[0].id;
+      const details = await client.graph.getNodeDetails({ nodeId });
+
+      expect(details).toBeDefined();
+      expect(details.node).toBeDefined();
+      expect(details.node.id).toBe(nodeId);
+      expect(Array.isArray(details.edges)).toBe(true);
+      expect(Array.isArray(details.connectedNodes)).toBe(true);
+    });
+
+    it('should throw validation error for missing nodeId', async () => {
+      await expect(
+        client.graph.getNodeDetails({ nodeId: '' })
+      ).rejects.toThrow('Node ID is required');
+    });
+  });
+
+  describe('getNodeEdges', () => {
+    it('should fetch node edges', async () => {
+      // First get a node ID
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        limit: 1,
+      });
+
+      if (graphData.nodes.length === 0) {
+        console.warn('No nodes available for testing getNodeEdges');
+        return;
+      }
+
+      const nodeId = graphData.nodes[0].id;
+      const result = await client.graph.getNodeEdges({ nodeId });
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.edges)).toBe(true);
+      expect(Array.isArray(result.connectedNodes)).toBe(true);
+    });
+
+    it('should support edge type filtering', async () => {
+      // First get a node ID
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        limit: 1,
+      });
+
+      if (graphData.nodes.length === 0) {
+        console.warn('No nodes available for testing edge filtering');
+        return;
+      }
+
+      const nodeId = graphData.nodes[0].id;
+      const result = await client.graph.getNodeEdges({
+        nodeId,
+        edgeTypes: ['extends'],
+      });
+
+      expect(result.edges.every(e => e.type === 'extends')).toBe(true);
+    });
+
+    it('should throw validation error for missing nodeId', async () => {
+      await expect(
+        client.graph.getNodeEdges({ nodeId: '' })
+      ).rejects.toThrow('Node ID is required');
+    });
+  });
+
+  describe('getAllGraphPages', () => {
+    it('should paginate through all pages', async () => {
+      const allNodes: GraphNode[] = [];
+      const allNodeIds = new Set<string>();
+      let pageCount = 0;
+
+      for await (const page of client.graph.getAllGraphPages({
+        spaceId: testSpaceId,
+        limit: 5,
+      })) {
+        expect(page).toBeDefined();
+        expect(Array.isArray(page.nodes)).toBe(true);
+        
+        // Collect nodes
+        for (const node of page.nodes) {
+          // Verify no duplicates
+          expect(allNodeIds.has(node.id)).toBe(false);
+          allNodeIds.add(node.id);
+          allNodes.push(node);
+        }
+
+        pageCount++;
+        
+        // Safety limit
+        if (pageCount >= 10) break;
+      }
+
+      // Should have collected some nodes
+      expect(allNodes.length).toBeGreaterThan(0);
+      
+      // All node IDs should be unique
+      expect(allNodeIds.size).toBe(allNodes.length);
+    });
+
+    it('should handle empty results', async () => {
+      const pages: GraphData[] = [];
+
+      for await (const page of client.graph.getAllGraphPages({
+        spaceId: 'non-existent-space',
+        limit: 5,
+      })) {
+        pages.push(page);
+        
+        // Should only get one empty page
+        if (pages.length >= 1) break;
+      }
+
+      expect(pages.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should respect filters across pages', async () => {
+      const allNodes: GraphNode[] = [];
+
+      for await (const page of client.graph.getAllGraphPages({
+        spaceId: testSpaceId,
+        nodeTypes: ['memory'],
+        limit: 5,
+      })) {
+        allNodes.push(...page.nodes);
+        
+        // Verify all nodes match filter
+        expect(page.nodes.every(n => n.type === 'memory')).toBe(true);
+        
+        // Safety limit
+        if (allNodes.length >= 20) break;
+      }
+
+      // All collected nodes should match filter
+      expect(allNodes.every(n => n.type === 'memory')).toBe(true);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('should have correct TypeScript types', async () => {
+      const graphData = await client.graph.getGraph({
+        spaceId: testSpaceId,
+        limit: 1,
+      });
+
+      // These should compile without errors
+      const node: GraphNode = graphData.nodes[0];
+      const nodeId: string = node.id;
+      const nodeType: 'memory' | 'document' | 'entity' = node.type;
+      const label: string = node.label;
+      const createdAt: string = node.data.createdAt;
+
+      expect(nodeId).toBeDefined();
+      expect(nodeType).toBeDefined();
+      expect(label).toBeDefined();
+      expect(createdAt).toBeDefined();
+    });
+  });
+});