@js4cytoscape/ndex-client 0.5.0-alpha.9 → 0.6.0-alpha.2

package/src/index.ts

@@ -0,0 +1,230 @@
+/**
+ * NDEx Client Library - Modern TypeScript Implementation
+ * 
+ * A comprehensive, modern TypeScript client for the NDEx (Network Data Exchange) API.
+ * Supports both v2 and v3 APIs with intelligent version routing, native CX2 format support,
+ * and provides a clean, type-safe interface for network operations.
+ */
+
+// Core Types
+export * from './types';
+
+// Models
+export { CX2Network } from './models/CX2Network';
+
+// Core Services
+export { NetworkServiceV2 } from './services/NetworkServiceV2';
+export { NetworkServiceV3 } from './services/NetworkServiceV3';
+export { UnifiedNetworkService } from './services/UnifiedNetworkService';
+export { FilesService } from './services/FilesService';
+export { WorkspaceService } from './services/WorkspaceService';
+export { UserService } from './services/UserService';
+export { AdminService } from './services/AdminService';
+export { CyNDExService } from './services/CyNDExService';
+
+// Backward compatibility alias
+export { CyNDExService as CyNDEx } from './services/CyNDExService';
+
+// Legacy compatibility exports - temporarily commented out for test setup
+// TODO: Fix ES module compatibility for NDEx.js and CyNDEx.js
+// export { default as NDEx } from './NDEx.js';
+// export { default as CyNDEx } from './CyNDEx.js';
+
+// Main Client Class
+import { HTTPService } from './services/HTTPService';
+import { UnifiedNetworkService } from './services/UnifiedNetworkService';
+import { FilesService } from './services/FilesService';
+import { WorkspaceService } from './services/WorkspaceService';
+import { UserService } from './services/UserService';
+import { AdminService } from './services/AdminService';
+import { NDExClientConfig, BasicAuth, OAuthAuth } from './types';
+
+/**
+ * NDExClient - Main client class for NDEx API operations
+ * 
+ * Provides a unified interface for all NDEx operations with intelligent
+ * version routing between v2 and v3 APIs.
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const client = new NDExClient({
+ *   baseURL: 'https://www.ndexbio.org',
+ *   debug: true
+ * });
+ * 
+ * // Authenticate
+ * await client.user.authenticate({ username: 'user', password: 'pass' });
+ * 
+ * // Search networks
+ * const results = await client.networks.searchNetworks({ searchString: 'pathway' });
+ * 
+ * // Get network as CX2
+ * const network = await client.networks.getNetworkAsCX2Object('network-uuid');
+ * 
+ * // User operations
+ * const profile = await client.user.getCurrentUser();
+ * 
+ * // Admin operations (requires admin privileges)
+ * const stats = await client.admin.getSystemStats();
+ * ```
+ */
+export class NDExClient {
+  private httpService: HTTPService;
+  
+  /** Network operations with intelligent v2/v3 routing */
+  public readonly networks: UnifiedNetworkService;
+  
+  /** File upload/download and task management */
+  public readonly files: FilesService;
+  
+  /** Workspace operations (deprecated - most functionality moved to other services) */
+  public readonly workspace: WorkspaceService;
+  
+  /** User authentication and management */
+  public readonly user: UserService;
+  
+  /** System administration operations */
+  public readonly admin: AdminService;
+
+  constructor(config: NDExClientConfig = {}) {
+    this.httpService = new HTTPService(config);
+    this.networks = new UnifiedNetworkService(this.httpService);
+    this.files = new FilesService(this.httpService);
+    this.workspace = new WorkspaceService(this.httpService);
+    this.user = new UserService(this.httpService);
+    this.admin = new AdminService(this.httpService);
+  }
+
+
+  /**
+   * Clear authentication
+   */
+  logout(): void {
+    this.httpService.updateConfig({ auth: undefined });
+  }
+
+  /**
+   * Get server status information
+   * Can be called by authenticated or anonymous users.
+   * @param format - Optional format parameter. Use 'full' for detailed information including properties and importers/exporters
+   * @returns Server status including network/user counts and optional server details
+   */
+  async getServerStatus(format?: 'full'): Promise<{
+    message: string;
+    properties?: {
+      ServerVersion: string;
+      Build: string;
+      ServerResultLimit: string;
+      ImporterExporters: Array<{
+        importer: boolean;
+        exporter: boolean;
+        fileExtension: string;
+        name: string;
+        description: string;
+      }>;
+    };
+    networkCount: number;
+    userCount: number;
+    groupCount?: number;
+  }> {
+    const params = new URLSearchParams();
+    if (format) {
+      params.append('format', format);
+    }
+
+    const endpoint = `admin/status${params.toString() ? `?${params.toString()}` : ''}`;
+    return this.httpService.get(endpoint);
+  }
+
+  /**
+   * Check if client has valid authentication information configured
+   * @returns true if auth is a valid BasicAuth or OAuthAuth object, false otherwise
+   */
+  hasAuthInfo(): boolean {
+    const auth = this.httpService.getConfig().auth;
+    if (!auth) return false;
+    
+    // Check for BasicAuth structure
+    if (auth.type === 'basic') {
+      return !!(auth as BasicAuth).username && !!(auth as BasicAuth).password;
+    }
+    
+    // Check for OAuthAuth structure  
+    if (auth.type === 'oauth') {
+      return !!(auth as OAuthAuth).idToken;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Update client configuration
+   */
+  updateConfig(config: Partial<NDExClientConfig>): void {
+    this.httpService.updateConfig(config);
+  }
+
+  /**
+   * Get current client configuration
+   */
+  getConfig(): NDExClientConfig {
+    return this.httpService.getConfig();
+  }
+
+
+  /**
+   * Access to low-level HTTP service for advanced usage
+   */
+  get http(): HTTPService {
+    return this.httpService;
+  }
+
+  /**
+   * Access to version-specific network services for advanced usage
+   */
+  get v2() {
+    return {
+      networks: this.networks.v2,
+    };
+  }
+
+  get v3() {
+    return {
+      networks: this.networks.v3,
+    };
+  }
+
+}
+
+// Main export - New modern client (named export for better tree-shaking)
+// Users should import as: import { NDExClient } from '@js4cytoscape/ndex-client'
+
+// Version information - imported from package.json to ensure consistency
+import { version as packageVersion } from '../package.json';
+
+/**
+ * Library version string imported from package.json
+ * 
+ * Provides programmatic access to the current library version for:
+ * - Runtime version checking and validation
+ * - Debugging and error reporting
+ * - Logging and telemetry
+ * - Version-dependent feature detection
+ * 
+ * @example
+ * ```typescript
+ * import { NDExClient, version } from '@js4cytoscape/ndex-client';
+ * 
+ * console.log(`Using NDEx Client v${version}`);
+ * 
+ * // In error reports
+ * const errorReport = {
+ *   error: err.message,
+ *   libraryVersion: version,
+ *   timestamp: new Date().toISOString()
+ * };
+ * ```
+ */
+export const version = packageVersion;
+

package/src/models/CX2Network.ts

@@ -0,0 +1,423 @@
+import { 
+  CX2Network as CX2NetworkType,
+  CX2MetaData,
+  CX2Node,
+  CX2Edge,
+  CX2AttributeDeclarations,
+  CX2NetworkAttribute,
+  CX2NodeBypass,
+  CX2EdgeBypass,
+  CX2VisualProperty,
+  NetworkSummaryV3
+} from '../types';
+
+/**
+ * CX2Network - Modern representation of CX2 format networks
+ * Provides utilities for creating, manipulating, and validating CX2 networks
+ */
+export class CX2Network implements CX2NetworkType {
+  CXVersion: string = '2.0';
+  hasFragments: boolean = false;
+  metaData: CX2MetaData[] = [];
+  attributeDeclarations?: CX2AttributeDeclarations;
+  networkAttributes?: CX2NetworkAttribute[];
+  nodes?: CX2Node[];
+  edges?: CX2Edge[];
+  nodeBypass?: CX2NodeBypass[];
+  edgeBypass?: CX2EdgeBypass[];
+  visualProperties?: CX2VisualProperty;
+  status?: any[];
+
+  constructor(data?: Partial<CX2NetworkType>) {
+    if (data) {
+      Object.assign(this, data);
+    }
+    
+    // Ensure required metadata is present
+    this.ensureRequiredMetadata();
+  }
+
+  /**
+   * Create a new empty CX2Network
+   */
+  static createEmpty(): CX2Network {
+    const network = new CX2Network();
+    network.nodes = [];
+    network.edges = [];
+    network.metaData = [
+      {
+        name: 'nodes',
+        elementCount: 0
+      },
+      {
+        name: 'edges',
+        elementCount: 0
+      },
+    ];
+    return network;
+  }
+
+  /**
+   * Create CX2Network from raw JSON data
+   */
+  static fromJSON(json: string | object): CX2Network {
+    const data = typeof json === 'string' ? JSON.parse(json) : json;
+    return new CX2Network(data);
+  }
+
+  /**
+   * Create CX2Network from NetworkSummary (for compatibility)
+   */
+  static fromNetworkSummary(summary: NetworkSummaryV3): CX2Network {
+    const network = CX2Network.createEmpty();
+    
+    network.networkAttributes = [
+      { name: summary.name },
+      ...(summary.description ? [{ description: summary.description }] : []),
+      ...(summary.version ? [{ version: summary.version }] : []),
+    ];
+
+    // Add properties as network attributes
+    if (summary.properties) {
+      Object.entries(summary.properties).forEach(([key, value]) => {
+        network.networkAttributes?.push({
+          [key]: (value as { t: string; v: any }).v
+        });
+      });
+    }
+
+    return network;
+  }
+
+  /**
+   * Add a node to the network
+   */
+  addNode(id: number, attributes?: Record<string, any>): CX2Node {
+    if (!this.nodes) {
+      this.nodes = [];
+    }
+
+    const node: CX2Node = { id };
+    if (attributes) {
+      node.v = attributes;
+    }
+
+    this.nodes.push(node);
+    this.updateNodeCount();
+    return node;
+  }
+
+  /**
+   * Add an edge to the network
+   */
+  addEdge(id: number, sourceId: number, targetId: number, attributes?: Record<string, any>): CX2Edge {
+    if (!this.edges) {
+      this.edges = [];
+    }
+
+    const edge: CX2Edge = {
+      id,
+      s: sourceId,
+      t: targetId,
+    };
+
+    if (attributes) {
+      edge.v = attributes;
+    }
+
+    this.edges.push(edge);
+    this.updateEdgeCount();
+    return edge;
+  }
+
+  /**
+   * Add an individual node attribute
+   */
+  addNodeAttribute(nodeId: number, attributeName: string, value: any): void {
+
+    //find the nodes with the given ID
+    const node = this.nodes.find(n => n.id === nodeId);
+    //set the node attribute
+    if (node) {
+      if (!node.v) {
+        node.v = {};
+      }
+      node.v[attributeName] = value;
+    }
+
+  }
+
+  /**
+   * Add edge attributes (bulk)
+   */
+  addEdgeAttribute(edgeId: number, attributeName: string, value: any): void {
+    //similar to addNodeAttribute
+    const edge = this.edges.find(e => e.id === edgeId);
+    if (edge) {
+      if (!edge.v) {
+        edge.v = {};
+      }
+      edge.v[attributeName] = value;
+    }
+
+  
+  }
+
+  /**
+   * Set node coordinates
+   */
+  setNodeCoordinates(nodeId: number, x: number, y: number, z?: number): void {
+    if (!this.nodes) {
+      this.nodes = [];
+    }
+
+    // Find the node and update its coordinates directly
+    let node = this.nodes.find(n => n.id === nodeId);
+    
+    if (!node) {
+      // Create new node if it doesn't exist
+      node = { id: nodeId };
+      this.nodes.push(node);
+      this.updateNodeCount();
+    }
+
+    // Set coordinates directly on the node
+    node.x = x;
+    node.y = y;
+    if (z !== undefined) {
+      node.z = z;
+    }
+  }
+
+  /**
+   * Get node by ID
+   */
+  getNode(id: number): CX2Node | undefined {
+    return this.nodes?.find(node => node.id === id);
+  }
+
+  /**
+   * Get edge by ID
+   */
+  getEdge(id: number): CX2Edge | undefined {
+    return this.edges?.find(edge => edge.id === id);
+  }
+
+  /**
+   * Get all nodes
+   */
+  getNodes(): CX2Node[] {
+    return this.nodes || [];
+  }
+
+  /**
+   * Get all edges
+   */
+  getEdges(): CX2Edge[] {
+    return this.edges || [];
+  }
+
+  /**
+   * Get node count
+   */
+  getNodeCount(): number {
+    return this.nodes?.length || 0;
+  }
+
+  /**
+   * Get edge count
+   */
+  getEdgeCount(): number {
+    return this.edges?.length || 0;
+  }
+
+  /**
+   * Get network name from attributes
+   */
+  getNetworkName(): string | undefined {
+    return this.networkAttributes?.find(attr => 'name' in attr)?.name;
+  }
+
+  /**
+   * Set network name
+   */
+  setNetworkName(name: string): void {
+    if (!this.networkAttributes) {
+      this.networkAttributes = [];
+    }
+
+    // Remove existing name attribute
+    this.networkAttributes = this.networkAttributes.filter(attr => !('name' in attr));
+    
+    // Add new name
+    this.networkAttributes.push({ name });
+  }
+
+  /**
+   * Get network attribute by key
+   */
+  getNetworkAttribute(key: string): any {
+    return this.networkAttributes?.find(attr => key in attr)?.[key];
+  }
+
+  /**
+   * Set network attribute
+   */
+  setNetworkAttribute(key: string, value: any): void {
+    if (!this.networkAttributes) {
+      this.networkAttributes = [];
+    }
+
+    // Remove existing attribute with same key
+    this.networkAttributes = this.networkAttributes.filter(attr => !(key in attr));
+    
+    // Add new attribute
+    this.networkAttributes.push({ [key]: value });
+  }
+
+  /**
+   * Validate the CX2 network structure
+   */
+  validate(): { isValid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    // Check required fields
+    if (!this.CXVersion) {
+      errors.push('CXVersion is required');
+    }
+
+    if (this.hasFragments === undefined) {
+      errors.push('hasFragments is required');
+    }
+
+    if (!this.metaData || this.metaData.length === 0) {
+      errors.push('metaData is required and must not be empty');
+    }
+
+    // Validate metadata
+    this.metaData?.forEach((meta, index) => {
+      if (!meta.name) {
+        errors.push(`metaData[${index}] is missing required 'name' field`);
+      }
+    });
+
+    // Validate nodes
+    if (this.nodes) {
+      this.nodes.forEach((node, index) => {
+        if (node.id === undefined || node.id === null) {
+          errors.push(`nodes[${index}] is missing required 'id' field`);
+        }
+      });
+    }
+
+    // Validate edges
+    if (this.edges) {
+      this.edges.forEach((edge, index) => {
+        if (edge.id === undefined || edge.id === null) {
+          errors.push(`edges[${index}] is missing required 'id' field`);
+        }
+        if (edge.s === undefined || edge.s === null) {
+          errors.push(`edges[${index}] is missing required 's' (source) field`);
+        }
+        if (edge.t === undefined || edge.t === null) {
+          errors.push(`edges[${index}] is missing required 't' (target) field`);
+        }
+
+        // Check if source and target nodes exist
+        if (this.nodes && edge.s !== undefined && edge.t !== undefined) {
+          const sourceExists = this.nodes.some(node => node.id === edge.s);
+          const targetExists = this.nodes.some(node => node.id === edge.t);
+          
+          if (!sourceExists) {
+            errors.push(`edges[${index}] references non-existent source node ${edge.s}`);
+          }
+          if (!targetExists) {
+            errors.push(`edges[${index}] references non-existent target node ${edge.t}`);
+          }
+        }
+      });
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Convert to JSON string
+   */
+  toJSON(): string {
+    return JSON.stringify(this, null, 2);
+  }
+
+  /**
+   * Create a deep copy of the network
+   */
+  clone(): CX2Network {
+    return new CX2Network(JSON.parse(this.toJSON()));
+  }
+
+  /**
+   * Get basic statistics about the network
+   */
+  getStatistics() {
+    return {
+      nodeCount: this.getNodeCount(),
+      edgeCount: this.getEdgeCount(),
+      hasCoordinates: Boolean(this.nodes && this.nodes.some(node => 
+        node.x !== undefined || node.y !== undefined || node.z !== undefined
+      )),
+      hasVisualProperties: Boolean(this.visualProperties && (
+        this.visualProperties.default || 
+        this.visualProperties.edgeMapping || 
+        this.visualProperties.nodeMapping
+      ))
+    };
+  }
+
+  /**
+   * Ensure required metadata is present
+   */
+  private ensureRequiredMetadata(): void {
+    if (!this.metaData) {
+      this.metaData = [];
+    }
+
+    // Ensure nodes metadata exists
+    if (this.nodes && !this.metaData.find(m => m.name === 'nodes')) {
+      this.metaData.push({
+        name: 'nodes',
+        elementCount: this.nodes.length
+      });
+    }
+
+    // Ensure edges metadata exists  
+    if (this.edges && !this.metaData.find(m => m.name === 'edges')) {
+      this.metaData.push({
+        name: 'edges',
+        elementCount: this.edges.length
+      });
+    }
+  }
+
+  /**
+   * Update node count in metadata
+   */
+  private updateNodeCount(): void {
+    const nodesMeta = this.metaData?.find(m => m.name === 'nodes');
+    if (nodesMeta) {
+      nodesMeta.elementCount = this.nodes?.length || 0;
+    }
+  }
+
+  /**
+   * Update edge count in metadata
+   */
+  private updateEdgeCount(): void {
+    const edgesMeta = this.metaData?.find(m => m.name === 'edges');
+    if (edgesMeta) {
+      edgesMeta.elementCount = this.edges?.length || 0;
+    }
+  }
+}

package/src/services/AdminService.ts

@@ -0,0 +1,10 @@
+import { HTTPService } from './HTTPService';
+
+/**
+ * AdminService - NDEx admin operations
+ * Handles system administration and user management for admin users
+ */
+export class AdminService {
+  constructor(private http: HTTPService) {}
+
+}