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

package/src/services/CyNDExService.ts

@@ -0,0 +1,338 @@
+import axios, { AxiosInstance } from 'axios';
+import {
+  CyNDExConfig,
+  CyNDExAuthConfig,
+  NDExImportParams,
+  NDExExportParams,
+  CytoscapeNetworkSummary,
+  CyNDExStatusResponse,
+  CX2ImportParams
+} from '../types/cytoscape';
+
+/**
+ * CyNDEx Service - Cytoscape-NDEx Bridge
+ * 
+ * Provides seamless integration between Cytoscape desktop application and NDEx,
+ * enabling import/export of networks with support for CX and CX2 formats.
+ * 
+ * This service communicates with Cytoscape via its REST API and handles NDEx
+ * authentication parameters that are passed to Cytoscape for NDEx operations.
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const cyNDEx = new CyNDExService();
+ * 
+ * // Configure NDEx server
+ * cyNDEx.setNDExBaseURL('https://www.ndexbio.org');
+ * 
+ * // Set authentication
+ * cyNDEx.setBasicAuth('username', 'password');
+ * // or
+ * cyNDEx.setAuthToken('oauth-id-token');
+ * 
+ * // Import network from NDEx to Cytoscape
+ * await cyNDEx.postNDExNetworkToCytoscape('network-uuid', 'access-key');
+ * 
+ * // Export network from Cytoscape to NDEx
+ * await cyNDEx.postCytoscapeNetworkToNDEx('current');
+ * 
+ * // Import CX2 data to Cytoscape
+ * await cyNDEx.postCX2NetworkToCytoscape(cx2String, 'My Network', 'My Collection');
+ * ```
+ */
+export class CyNDExService {
+  private _port: number;
+  private cyRestBaseURL: string;
+  private ndexBaseURL: string;
+  private authConfig?: CyNDExAuthConfig;
+  private axiosInstance: AxiosInstance;
+
+  /**
+   * Create a new CyNDEx service instance
+   * 
+   * @param port - Port number for Cytoscape REST API (default: 1234)
+   * @param config - Optional configuration object
+   */
+  constructor(port: number = 1234, config?: CyNDExConfig) {
+    this._port = port;
+    this.cyRestBaseURL = config?.cyRestBaseURL || 'http://127.0.0.1';
+    this.ndexBaseURL = config?.ndexBaseURL || 'https://www.ndexbio.org';
+
+    // Create axios instance for Cytoscape REST API calls
+    this.axiosInstance = axios.create({
+      baseURL: this.cyRestURL(),
+      timeout: 30000,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Get the port number for Cytoscape REST API
+   */
+  get port(): number {
+    return this._port;
+  }
+
+  /**
+   * Get the base URL for Cytoscape REST API
+   */
+  static get cyRestBaseURL(): string {
+    return 'http://127.0.0.1';
+  }
+
+  /**
+   * Set NDEx server base URL
+   * 
+   * @param ndexBaseURL - Complete base URL for NDEx server (e.g., 'https://www.ndexbio.org')
+   *                      Must include protocol (https:// or http://)
+   * 
+   * @example
+   * ```typescript
+   * cyNDEx.setNDExBaseURL('https://www.ndexbio.org');
+   * cyNDEx.setNDExBaseURL('https://test.ndexbio.org');
+   * ```
+   */
+  setNDExBaseURL(ndexBaseURL: string): void {
+    if (ndexBaseURL?.trim()) {
+      this.ndexBaseURL = ndexBaseURL.trim();
+    }
+  }
+
+  /**
+   * Get the current NDEx server base URL
+   * 
+   * @returns Complete NDEx server base URL
+   */
+  getNDExBaseURL(): string {
+    return this.ndexBaseURL;
+  }
+
+
+  /**
+   * Set basic authentication credentials for NDEx operations
+   * 
+   * @param username - NDEx username
+   * @param password - NDEx password
+   */
+  setBasicAuth(username: string, password: string): void {
+    if (username?.trim() && password) {
+      this.authConfig = {
+        type: 'basic',
+        username: username.trim(),
+        password: password
+      };
+    }
+  }
+
+  /**
+   * Set OAuth ID token for NDEx operations
+   * 
+   * @param idToken - OAuth ID token from authentication provider
+   */
+  setAuthToken(idToken: string): void {
+    if (idToken?.trim()) {
+      this.authConfig = {
+        type: 'oauth',
+        idToken: idToken.trim()
+      };
+    }
+  }
+
+  /**
+   * Clear authentication credentials
+   */
+  clearAuth(): void {
+    this.authConfig = undefined;
+  }
+
+  /**
+   * Get the complete Cytoscape REST API URL
+   * 
+   * @returns Complete URL for Cytoscape REST API
+   */
+  cyRestURL(): string {
+    return `${this.cyRestBaseURL}:${this._port}`;
+  }
+
+  /**
+   * Get authorization fields for NDEx operations
+   * These are passed as parameters to Cytoscape for NDEx authentication
+   * 
+   * @private
+   * @returns Authorization parameters object
+   */
+  private getAuthFields(): Record<string, string> {
+    if (!this.authConfig) return {};
+
+    switch (this.authConfig.type) {
+      case 'basic':
+        return {
+          username: this.authConfig.username!,
+          password: this.authConfig.password!
+        };
+      case 'oauth':
+        return {
+          idToken: this.authConfig.idToken!
+        };
+      default:
+        return {};
+    }
+  }
+
+  /**
+   * Perform HTTP GET request to Cytoscape REST API
+   * 
+   * @private
+   * @param url - Endpoint URL (relative to base URL)
+   * @returns Promise resolving to response data
+   */
+  private async _httpGet<T = any>(url: string): Promise<T> {
+    const response = await this.axiosInstance.get<T>(url);
+    return response.data;
+  }
+
+  /**
+   * Perform HTTP POST request to Cytoscape REST API
+   * 
+   * @private
+   * @param url - Endpoint URL (relative to base URL)
+   * @param params - Optional query parameters
+   * @param data - Optional request body data
+   * @returns Promise resolving to response data
+   */
+  private async _httpPost<T = any>(url: string, params?: any, data?: any): Promise<T> {
+    const response = await this.axiosInstance.post<T>(url, data, { params });
+    return response.data;
+  }
+
+  /**
+   * Perform HTTP PUT request to Cytoscape REST API
+   * 
+   * @private
+   * @param url - Endpoint URL (relative to base URL)
+   * @param params - Optional query parameters
+   * @param data - Optional request body data
+   * @returns Promise resolving to response data
+   */
+  private async _httpPut<T = any>(url: string, params?: any, data?: any): Promise<T> {
+    const response = await this.axiosInstance.put<T>(url, data, { params });
+    return response.data;
+  }
+
+  // =============================================================================
+  // Public API Methods - Maintain exact same signatures as original CyNDEx.js
+  // =============================================================================
+
+  /**
+   * Get CyNDEx plugin status from Cytoscape
+   * 
+   * @returns Promise resolving to CyNDEx status information
+   */
+  async getCyNDExStatus(): Promise<CyNDExStatusResponse> {
+    return this._httpGet<CyNDExStatusResponse>('/cyndex2/v1');
+  }
+
+  /**
+   * Get network summary information from Cytoscape
+   * 
+   * @param suid - Network SUID or 'current' for current network (default: 'current')
+   * @returns Promise resolving to network summary
+   */
+  async getCytoscapeNetworkSummary(suid: string = 'current'): Promise<CytoscapeNetworkSummary> {
+    return this._httpGet<CytoscapeNetworkSummary>(`/cyndex2/v1/networks/${suid}`);
+  }
+
+  /**
+   * Import network from NDEx to Cytoscape
+   * 
+   * @param uuid - NDEx network UUID
+   * @param accessKey - Optional access key for private networks
+   * @param createView - Whether to create a network view (default: undefined)
+   * @returns Promise resolving to import result
+   */
+  async postNDExNetworkToCytoscape(
+    uuid: string, 
+    accessKey?: string, 
+    createView?: boolean
+  ): Promise<any> {
+    const importParams: NDExImportParams = {
+      serverUrl: `${this.ndexBaseURL}/v2`,
+      uuid: uuid,
+      accessKey: accessKey,
+      createView: createView,
+      ...this.getAuthFields()
+    };
+
+    return this._httpPost('/cyndex2/v1/networks', undefined, importParams);
+  }
+
+  /**
+   * Import CX network data to Cytoscape
+   * 
+   * @param cx - CX format network data
+   * @returns Promise resolving to import result
+   */
+  async postCXNetworkToCytoscape(cx: any): Promise<any> {
+    return this._httpPost('/cyndex2/v1/networks/cx', undefined, cx);
+  }
+
+  /**
+   * Import CX2 network data to Cytoscape
+   * 
+   * @param cx2_string - CX2 format network data as string
+   * @param title - Network title
+   * @param collection_name - Collection name
+   * @returns Promise resolving to import result
+   */
+  async postCX2NetworkToCytoscape(
+    cx2_string: string, 
+    title: string, 
+    collection_name: string
+  ): Promise<any> {
+    const params: CX2ImportParams = {
+      format: 'cx2',
+      collection: collection_name,
+      title: title
+    };
+
+    return this._httpPost('/v1/networks', params, cx2_string);
+  }
+
+  /**
+   * Export network from Cytoscape to NDEx (create new network)
+   * 
+   * @param suid - Network SUID or 'current' for current network (default: 'current')
+   * @returns Promise resolving to export result
+   */
+  async postCytoscapeNetworkToNDEx(suid: string = 'current'): Promise<any> {
+    const saveParams: NDExExportParams = {
+      serverUrl: `${this.ndexBaseURL}/v2`,
+      ...this.getAuthFields()
+    };
+
+    return this._httpPost(`/cyndex2/v1/networks/${suid}`, undefined, saveParams);
+  }
+
+  /**
+   * Update existing network in NDEx with data from Cytoscape
+   * 
+   * @param suid - Network SUID or 'current' for current network (default: 'current')
+   * @param uuid - Target NDEx network UUID to update
+   * @returns Promise resolving to update result
+   */
+  async putCytoscapeNetworkInNDEx(suid: string = 'current', uuid: string): Promise<any> {
+    const saveParams: NDExExportParams = {
+      serverUrl: `${this.ndexBaseURL}/v2`,
+      uuid: uuid,
+      ...this.getAuthFields()
+    };
+
+    return this._httpPut(`/cyndex2/v1/networks/${suid}`, undefined, saveParams);
+  }
+}
+
+// Export both as named export and default for backward compatibility
+export default CyNDExService;

package/src/services/FilesService.ts

@@ -0,0 +1,234 @@
+import { HTTPService } from './HTTPService';
+
+// Type definitions for better type safety
+interface ShareData {
+  files: Record<string, 'NETWORK' | 'FOLDER' | 'SHORTCUT'>;
+}
+
+interface MemberData {
+  members: Record<string, 'READ' | 'WRITE'>;
+}
+
+interface UpdateMemberRequest {
+  files: ShareData['files'];
+  members: MemberData['members'];
+}
+
+interface TransferOwnershipRequest {
+  files: ShareData['files'];
+  new_owner: string;
+}
+
+/**
+ * FilesService - NDEx file operations and task management
+ * Handles file uploads, downloads, exports, and asynchronous task tracking
+ */
+export class FilesService {
+  constructor(private http: HTTPService) {}
+
+  /**
+   * Copy a file to a different location
+   * @param fromUuid - Source file UUID
+   * @param toPath - Target path
+   * @param type - File type (NETWORK, FOLDER, SHORTCUT)
+   * @param accessKey - Optional access key for protected files
+   */
+  copyFile(fromUuid: string, toPath: string, type: string, accessKey?: string): Promise<any> {
+    let parameters: Record<string, any> = {};
+
+    if (accessKey !== undefined) {
+      parameters['accesskey'] = accessKey;
+    }
+    return this.http.post('files/copy', {from_uuid: fromUuid, type: type, to_path: toPath}, {params: parameters, version: 'v3'});
+  }
+
+  /** Get file count statistics for the current user */
+  getCount(): Promise<any> {
+    return this.http.get('files/count', {version: 'v3'});
+  }
+
+  /** Get files in the trash for the current user */
+  getTrash(): Promise<any> {
+    return this.http.get('files/trash', {version: 'v3'});
+  }
+
+  /** Permanently delete all files in trash */
+  emptyTrash(): Promise<any> {
+    return this.http.delete('files/trash', {version: 'v3'});
+  }
+
+  /**
+   * Permanently delete a file from trash
+   * @param fileId - File UUID to permanently delete
+   */
+  permanentlyDeleteFile(fileId: string): Promise<any> {
+    return this.http.delete(`files/trash/${fileId}`, { version: 'v3' });
+  }
+
+  /**
+   * Restore files from trash
+   * @param networkIds - Array of network UUIDs to restore
+   * @param folderIds - Array of folder UUIDs to restore  
+   * @param shortcutIds - Array of shortcut UUIDs to restore
+   */
+  restoreFile(networkIds: string[], folderIds: string[], shortcutIds: string[]): Promise<any> {
+    return this.http.post('files/trash/restore', {networks: networkIds, folders: folderIds, shortcuts: shortcutIds}, {version: 'v3'});
+  }
+
+  private _validateShareData(data: any): void {
+    // Check if data is an object and has files property
+    if (typeof data !== 'object' || data === null || data.files === undefined) {
+      throw new Error('Data must be an object with a "files" property');
+    }
+    
+    // Check if files is an object
+    if (typeof data.files !== 'object' || data.files === null) {
+      throw new Error('The "files" property must be an object');
+    }
+    
+    // Check each key-value pair in files
+    const validValues = ['NETWORK', 'FOLDER', 'SHORTCUT'];
+    
+    for (const [uuid, fileType] of Object.entries(data.files)) {
+      // Validate UUID format (basic validation)
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+        throw new Error(`Invalid UUID format: ${uuid}`);
+      }
+      
+      // Validate file type
+      if (!validValues.includes(fileType as string)) {
+        throw new Error(`Invalid file type for ${uuid}: ${fileType}. Must be one of: ${validValues.join(', ')}`);
+      }
+    }
+  }
+
+  private _validateMemberData(data: any): void {
+    if (typeof data !== 'object' || data === null || data.members === undefined) {
+      throw new Error('Data must be an object with a "members" property');
+    }
+    const validValues = ['READ', 'WRITE'];
+    for (const [uuid, permission] of Object.entries(data.members)) {
+      if (!validValues.includes(permission as string)) {
+        throw new Error(`Invalid permission for ${uuid}: ${permission}. Must be one of: ${validValues.join(', ')}`);
+      }
+      if (typeof uuid !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+        throw new Error(`Invalid UUID format: ${uuid}`);
+      }
+    }
+  }
+
+  updateMember(files: ShareData['files'], members: MemberData['members']): Promise<any> {
+    this._validateShareData({ files });
+    this._validateMemberData({ members });
+    return this.http.post('files/sharing/members', { files, members }, { version: 'v3' });
+  }
+
+  listMembers(files: any): Promise<any> {
+    return this.http.get('files/sharing/members/list', {params: files, version: 'v3'});
+  }
+
+  transferOwnership(files: ShareData['files'], newOwner: string): Promise<any> {
+    this._validateShareData({ files });
+    return this.http.post('files/sharing/transfer_ownership', { files, new_owner: newOwner }, { version: 'v3' });
+  }
+
+  listShares(limit?: number): Promise<any> {
+    const parameters: Record<string, any> = {};
+    if (limit !== undefined) {
+      parameters['limit'] = limit;
+    }
+    return this.http.post('files/sharing/list', parameters, { version: 'v3' });
+  }
+  
+  share(files: ShareData['files']): Promise<any> {
+    this._validateShareData({ files });
+    return this.http.post('files/sharing/share', { files }, { version: 'v3' });
+  }
+
+  unshare(files: ShareData['files']): Promise<any> {
+    this._validateShareData({ files });
+    return this.http.post('files/sharing/unshare', { files }, { version: 'v3' });
+  }
+
+  // Folder operations
+  getFolders(limit?: number): Promise<any> {
+    let parameters: Record<string, any> = {};
+
+    if (limit !== undefined) {
+      parameters['limit'] = limit;
+    }
+    return this.http.get('files/folders', {params: parameters, version: 'v3'});
+  }
+  
+  createFolder(name: string, parentFolderId?: string): Promise<any> {
+    return this.http.post('files/folders', { name: name, parent: parentFolderId }, { version: 'v3' });
+  }
+
+  getFolder(folderId: string, accessKey?: string): Promise<any> {
+    const parameters: Record<string, any> = {};
+    if (accessKey !== undefined) {
+      parameters['accesskey'] = accessKey;
+    }
+    return this.http.get(`files/folders/${folderId}`, { params: parameters, version: 'v3' });
+  }
+
+  updateFolder(folderId: string, name: string, parentFolderId?: string): Promise<any> {
+    return this.http.put(`files/folders/${folderId}`, { name: name, parent: parentFolderId }, { version: 'v3' });
+  }
+
+  deleteFolder(folderId: string): Promise<any> {
+    return this.http.delete(`files/folders/${folderId}`, { version: 'v3' });
+  }
+
+  getFolderCount(folderId: string, accessKey?: string): Promise<any> {
+    const parameters: Record<string, any> = {};
+    if (accessKey !== undefined) {
+      parameters['accesskey'] = accessKey;
+    }
+    return this.http.get(`files/folders/${folderId}/count`, { params: parameters, version: 'v3' });
+  }
+
+  getFolderList(folderId: string, accessKey?: string, format?: string, type?: string): Promise<any> {
+    const parameters: Record<string, any> = {};
+    if (accessKey !== undefined) {
+      parameters['accesskey'] = accessKey;
+    }
+    if (format !== undefined) {
+      parameters['format'] = format;
+    }
+    if (type !== undefined) {
+      parameters['type'] = type;
+    }
+    return this.http.get(`files/folders/${folderId}/list`, { params: parameters, version: 'v3' });
+  }
+
+  // Shortcut operations
+  getShortcuts(limit?: number): Promise<any> {
+    let parameters: Record<string, any> = {};
+
+    if (limit !== undefined) {
+      parameters['limit'] = limit;
+    }
+    return this.http.get('files/shortcuts', {params: parameters, version: 'v3'});
+  }
+
+  createShortcut(name: string, parentFolderId?: string, targetId?: string, targetType?: string): Promise<any> {
+    return this.http.post('files/shortcuts', { name: name, parent: parentFolderId, target: targetId, targetType }, { version: 'v3' });
+  }
+
+  getShortcut(shortcutId: string, accessKey?: string): Promise<any> {
+    const parameters: Record<string, any> = {};
+    if (accessKey !== undefined) {
+      parameters['accesskey'] = accessKey;
+    }
+    return this.http.get(`files/shortcuts/${shortcutId}`, { params: parameters, version: 'v3' });
+  }
+  
+  updateShortcut(shortcutId: string, name: string, parentFolderId?: string, targetId?: string, targetType?: string): Promise<any> {
+    return this.http.put(`files/shortcuts/${shortcutId}`, { name: name, parent: parentFolderId, target: targetId, targetType }, { version: 'v3' });
+  }
+
+  deleteShortcut(shortcutId: string): Promise<any> {
+    return this.http.delete(`files/shortcuts/${shortcutId}`, { version: 'v3' });
+  }
+}