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

package/src/services/UserService.ts

@@ -0,0 +1,233 @@
+import { HTTPService } from './HTTPService';
+import { 
+  NDExUser,
+  PaginationParams,
+  NetworkSummaryV2
+} from '../types';
+
+/**
+ * UserService - NDEx user-related operations
+ * Handles authentication, user management, and user workspace operations
+ */
+export class UserService {
+  constructor(private http: HTTPService) {}
+
+  // ============================================================================
+  // Authentication Methods
+  // ============================================================================
+
+  /**
+   * Get authenticated user (equivalent to getSignedInUser from legacy client)
+   * Returns the current signed-in user object from NDEx server
+   * 
+   * For basic authentication: Gets the current user using the /user endpoint
+   * For OAuth authentication: Uses the /users/signin endpoint with ID token
+   * 
+   * @returns The authenticated user object
+   * @note When authenticating with OAuth ID token, if a user with matching email 
+   *       doesn't exist on the server, this function will automatically create 
+   *       that user and return the newly created user object.
+   */
+  async authenticate(): Promise<NDExUser> {
+    const authType = this.http.getAuthType();
+    if (!authType) {
+      throw new Error('Authentication parameters are missing in NDEx client.');
+    }
+    
+    if (authType === 'basic') {
+      // For basic auth, use the standard user endpoint with valid parameter
+      const endpoint = 'user';
+      const params = { valid: true };
+      return this.http.get<NDExUser>(endpoint, { params });
+    } else if (authType === 'oauth') {
+      // For OAuth, use the signin endpoint with ID token (v3 API)
+      const idToken = this.http.getIdToken();
+      if (!idToken) {
+        throw new Error('OAuth ID token is missing.');
+      }
+      
+      const endpoint = 'users/signin';
+      const data = { idToken };
+      return this.http.post<NDExUser>(endpoint, data, { version: 'v3' });
+    }
+    
+    throw new Error(`Unsupported authentication type: ${authType}`);
+  }
+
+  /**
+   * Get current user profile (equivalent to getSignedInUser from legacy client)
+   * Returns the current signed-in user object from NDEx server
+   * 
+   * Uses the /user endpoint with {valid: true} parameter for both basic and OAuth authentication.
+   * Unlike authenticate(), this function will NOT automatically create a user account for OAuth.
+   * If the OAuth ID token doesn't match an existing user, it will return an unauthorized error.
+   * 
+   * @returns The current user object
+   * @note This function requires existing authentication and will not create new users
+   */
+  async getCurrentUser(): Promise<NDExUser> {
+    const authType = this.http.getAuthType();
+    if (!authType) {
+      throw new Error('Authentication parameters are missing in NDEx client.');
+    }
+    
+    const endpoint = 'user';
+    const params = { valid: true };
+    return this.http.get<NDExUser>(endpoint, { params });
+  }
+
+  /**
+   * Update current user profile
+   * Uses the UUID from the userUpdate object and server validates against authenticated user
+   */
+  async updateCurrentUser(userUpdate: Partial<NDExUser>): Promise<void> {
+    if (!userUpdate.externalId) {
+      throw new Error('User uuid is required in userUpdate object');
+    }
+
+    const endpoint = `user/${userUpdate.externalId}`;
+    return this.http.put<void>(endpoint, userUpdate);
+  }
+
+
+  /**
+   * Request password reset
+   */
+  async requestPasswordReset(email: string): Promise<void> {
+    const endpoint = 'user/forgot-password';
+    return this.http.post<void>(endpoint, { email });
+  }
+
+  /**
+   * Reset password with user UUID (server validates UUID matches authenticated user)
+   * @param userUUID - User UUID (must match authenticated user)
+   * @param newPassword - New password as plain text
+   */
+  async resetPassword(userUUID: string, newPassword: string): Promise<void> {
+    const endpoint = `user/${userUUID}/password`;
+    const config: any = {
+      headers: {
+        'Content-Type': 'text/plain'  // Send password as plain text
+      }
+    };
+    
+    return this.http.put<void>(endpoint, newPassword, config);
+  }
+
+  // ============================================================================
+  // User Management Methods
+  // ============================================================================
+
+  /**
+   * Get user by UUID
+   */
+  async getUser(userUUID: string): Promise<NDExUser> {
+    const endpoint = `user/${userUUID}`;
+    return this.http.get<NDExUser>(endpoint);
+  }
+
+  /**
+   * Get user by account name or email (matches server getUserByAccountNameOrAuthenticatUser)
+   * @param searchBy - Search criteria - either by username OR by email, but not both
+   * @returns User object matching the search criteria
+   * @note If both username and email are provided, only username will be used
+   */
+  async getUserByNameOrEmail(searchBy: 
+    | { username: string }
+    | { email: string }
+  ): Promise<NDExUser> {
+    const params = new URLSearchParams();
+    
+    if ('username' in searchBy) {
+      params.append('username', searchBy.username);
+    } else if ('email' in searchBy) {
+      params.append('email', searchBy.email);
+    }
+
+    const endpoint = `user?${params.toString()}`;
+    return this.http.get<NDExUser>(endpoint);
+  }
+
+  /**
+   * Get multiple users by their UUIDs (batch operation)
+   * @param uuidList - Array of user UUIDs to fetch
+   * @returns Array of user objects corresponding to the provided UUIDs
+   */
+  async getUsersByUUIDs(uuidList: string[]): Promise<NDExUser[]> {
+    const endpoint = 'batch/user';
+    return this.http.post<NDExUser[]>(endpoint, uuidList);
+  }
+
+  /**
+   * Search users (equivalent to searchUsers from legacy client)
+   * @param searchTerms - Search string to find users
+   * @param start - Starting offset for pagination (optional)
+   * @param size - Maximum number of results to return (optional)
+   * @returns Array of users matching the search criteria
+   */
+  async searchUsers(
+    searchTerms: string, 
+    start?: number, 
+    size?: number
+  ): Promise<NDExUser[]> {
+    const params: Record<string, string> = {};
+    
+    if (start !== undefined) {
+      params.start = start.toString();
+    }
+    if (size !== undefined) {
+      params.limit = size.toString();
+    }
+
+    const data = { searchString: searchTerms };
+    const endpoint = 'search/user';
+    
+    return this.http.post<NDExUser[]>(endpoint, data, { params });
+  }
+
+
+  // ============================================================================
+  // User Network Methods
+  // ============================================================================
+
+  /**
+   * Get networks for a user's account page (equivalent to getAccountPageNetworks from legacy client)
+   * 
+   * @param userUUID - User UUID to get networks for
+   * @param offset - Starting offset for pagination (optional)
+   * @param limit - Maximum number of networks to return (optional)
+   * @returns Array of V2 network summaries for the specified user
+   * @note This function requires authentication. The auth attribute must be set in the client configuration.
+   */
+  async getAccountPageNetworks(
+    userUUID: string,
+    offset?: number, 
+    limit?: number
+  ): Promise<NetworkSummaryV2[]> {
+    // Build parameters for the network summary request
+    const params: Record<string, string> = {};
+    if (offset !== undefined) {
+      params.offset = offset.toString();
+    }
+    if (limit !== undefined) {
+      params.limit = limit.toString();
+    }
+
+    // Get network summaries for the user
+    const endpoint = `user/${userUUID}/networksummary`;
+    return this.http.get<NetworkSummaryV2[]>(endpoint, { params });
+  }
+
+
+
+  /**
+   * Delete user account (server validates userid matches authenticated user)
+   * @param userUUID - User UUID to delete (must match authenticated user)
+   * @note This function requires authentication. The auth attribute must be set in the client configuration.
+   * @note The userUUID parameter must be the UUID of the currently authenticated user. The server will validate this.
+   */
+  async deleteUserAccount(userUUID: string): Promise<void> {
+    const endpoint = `user/${userUUID}`;
+    return this.http.delete<void>(endpoint);
+  }
+}

package/src/services/WorkspaceService.ts

@@ -0,0 +1,159 @@
+import { HTTPService } from './HTTPService';
+import { CyWebWorkspace } from '../types';
+
+/**
+ * WorkspaceService - NDEx CyWeb workspace operations
+ * 
+ * Provides methods for managing CyWeb workspaces including creation, retrieval,
+ * updates, and deletion of workspaces and their associated networks.
+ * All workspace operations use the V3 API.
+ */
+export class WorkspaceService {
+  constructor(private http: HTTPService) {}
+
+  /**
+   * Create a new CyWeb workspace (migrated from original NDEx.js)
+   * 
+   * Creates a new workspace with the specified workspace data.
+   * 
+   * @param workspace - The workspace object to create
+   * @returns Promise resolving to the response from the server (typically contains workspace location)
+   * 
+   * @example
+   * ```typescript
+   * const workspaceData = {
+   *   name: "My Workspace",
+   *   description: "A sample workspace",
+   *   networkIds: []
+   * };
+   * const response = await client.workspace.createCyWebWorkspace(workspaceData);
+   * ```
+   */
+  async createCyWebWorkspace(workspace: CyWebWorkspace): Promise<string> {
+    const endpoint = 'workspaces';
+    return this.http.post<string>(endpoint, workspace, { version: 'v3' });
+  }
+
+  /**
+   * Get a CyWeb workspace by ID (migrated from original NDEx.js)
+   * 
+   * Retrieves a workspace and its details by workspace ID.
+   * 
+   * @param workspaceId - The UUID of the workspace to retrieve
+   * @returns Promise resolving to the workspace object
+   * 
+   * @example
+   * ```typescript
+   * const workspace = await client.workspace.getCyWebWorkspace('workspace-uuid');
+   * console.log(workspace.name);
+   * ```
+   */
+  async getCyWebWorkspace(workspaceId: string): Promise<CyWebWorkspace> {
+    const endpoint = `workspaces/${workspaceId}`;
+    return this.http.get<CyWebWorkspace>(endpoint, { version: 'v3' });
+  }
+
+  /**
+   * Delete a CyWeb workspace (migrated from original NDEx.js)
+   * 
+   * Deletes the specified workspace permanently.
+   * 
+   * @param workspaceId - The UUID of the workspace to delete
+   * @returns Promise resolving when the workspace is deleted
+   * 
+   * @example
+   * ```typescript
+   * await client.workspace.deleteCyWebWorkspace('workspace-uuid');
+   * ```
+   */
+  async deleteCyWebWorkspace(workspaceId: string): Promise<void> {
+    const endpoint = `workspaces/${workspaceId}`;
+    return this.http.delete<void>(endpoint, { version: 'v3' });
+  }
+
+  /**
+   * Update a CyWeb workspace (migrated from original NDEx.js)
+   * 
+   * Updates a workspace with new data, replacing the entire workspace object.
+   * 
+   * @param workspaceId - The UUID of the workspace to update
+   * @param workspaceObj - The updated workspace object
+   * @returns Promise resolving when the workspace is updated
+   * 
+   * @example
+   * ```typescript
+   * const updatedWorkspace = {
+   *   name: "Updated Workspace Name",
+   *   description: "Updated description",
+   *   networkIds: ["network-uuid-1", "network-uuid-2"]
+   * };
+   * await client.workspace.updateCyWebWorkspace('workspace-uuid', updatedWorkspace);
+   * ```
+   */
+  async updateCyWebWorkspace(workspaceId: string, workspaceObj: CyWebWorkspace): Promise<void> {
+    const endpoint = `workspaces/${workspaceId}`;
+    return this.http.put<void>(endpoint, workspaceObj, { version: 'v3' });
+  }
+
+  /**
+   * Update CyWeb workspace name (migrated from original NDEx.js)
+   * 
+   * Updates only the name of a workspace.
+   * 
+   * @param workspaceId - The UUID of the workspace to update
+   * @param newName - The new name for the workspace
+   * @returns Promise resolving when the workspace name is updated
+   * 
+   * @example
+   * ```typescript
+   * await client.workspace.updateCyWebWorkspaceName('workspace-uuid', 'New Workspace Name');
+   * ```
+   */
+  async updateCyWebWorkspaceName(workspaceId: string, newName: string): Promise<void> {
+    const endpoint = `workspaces/${workspaceId}/name`;
+    return this.http.put<void>(endpoint, { name: newName }, { version: 'v3' });
+  }
+
+  /**
+   * Update CyWeb workspace networks (migrated from original NDEx.js)
+   * 
+   * Updates the list of network IDs associated with a workspace.
+   * 
+   * @param workspaceId - The UUID of the workspace to update
+   * @param networkIds - Array of network UUIDs to associate with the workspace
+   * @returns Promise resolving when the workspace networks are updated
+   * 
+   * @example
+   * ```typescript
+   * const networkIds = ['network-uuid-1', 'network-uuid-2', 'network-uuid-3'];
+   * await client.workspace.updateCyWebWorkspaceNetworks('workspace-uuid', networkIds);
+   * ```
+   */
+  async updateCyWebWorkspaceNetworks(workspaceId: string, networkIds: string[]): Promise<void> {
+    const endpoint = `workspaces/${workspaceId}/networkids`;
+    return this.http.put<void>(endpoint, networkIds, { version: 'v3' });
+  }
+
+  /**
+   * Get user's CyWeb workspaces (migrated from original NDEx.js)
+   * 
+   * Retrieves all workspaces belonging to the currently authenticated user.
+   * Requires authentication.
+   * 
+   * @returns Promise resolving to array of workspace objects
+   * 
+   * @example
+   * ```typescript
+   * const workspaces = await client.workspace.getUserCyWebWorkspaces();
+   * workspaces.forEach(workspace => {
+   *   console.log(`Workspace: ${workspace.name}`);
+   * });
+   * ```
+   */
+  async getUserCyWebWorkspaces(): Promise<CyWebWorkspace[]> {
+    // First get the current user to get their externalId
+    const user = await this.http.get<any>('user', { params: { valid: true } });
+    const endpoint = `users/${user.externalId}/workspaces`;
+    return this.http.get<CyWebWorkspace[]>(endpoint, { version: 'v3' });
+  }
+}

package/src/types/cytoscape.ts

@@ -0,0 +1,81 @@
+/**
+ * Type definitions for CyNDEx (Cytoscape-NDEx Bridge) operations
+ */
+
+/**
+ * Configuration for CyNDEx service
+ */
+export interface CyNDExConfig {
+  /** Port number for Cytoscape REST API (default: 1234) */
+  port?: number;
+  /** Base URL for Cytoscape REST API (default: 'http://127.0.0.1') */
+  cyRestBaseURL?: string;
+  /** NDEx server base URL (default: 'https://www.ndexbio.org') */
+  ndexBaseURL?: string;
+}
+
+/**
+ * Authentication configuration for NDEx operations
+ * This is used as parameters passed to Cytoscape for NDEx authentication
+ */
+export interface CyNDExAuthConfig {
+  type: 'basic' | 'oauth';
+  username?: string;
+  password?: string;
+  idToken?: string;
+}
+
+/**
+ * Parameters for importing NDEx network to Cytoscape
+ */
+export interface NDExImportParams {
+  serverUrl: string;
+  uuid: string;
+  accessKey?: string;
+  createView?: boolean;
+  username?: string;
+  password?: string;
+  idToken?: string;
+}
+
+/**
+ * Parameters for exporting Cytoscape network to NDEx
+ */
+export interface NDExExportParams {
+  serverUrl: string;
+  uuid?: string;
+  username?: string;
+  password?: string;
+  idToken?: string;
+}
+
+/**
+ * Cytoscape network summary response
+ */
+export interface CytoscapeNetworkSummary {
+  suid?: string;
+  title?: string;
+  name?: string;
+  nodeCount?: number;
+  edgeCount?: number;
+  selected?: boolean;
+  [key: string]: any; // Allow additional properties from Cytoscape
+}
+
+/**
+ * CyNDEx status response
+ */
+export interface CyNDExStatusResponse {
+  version?: string;
+  status?: string;
+  [key: string]: any; // Allow additional status properties
+}
+
+/**
+ * CX2 import parameters for Cytoscape
+ */
+export interface CX2ImportParams {
+  format: 'cx2';
+  collection?: string;
+  title?: string;
+}