@js4cytoscape/ndex-client 0.6.0-alpha.1 → 0.6.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js4cytoscape/ndex-client",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-alpha.2",
   "description": "NDEx client library - Modern TypeScript implementation",
   "repository": {
     "type": "git",
@@ -32,10 +32,10 @@
     "build": "tsup",
     "build:docs": "typedoc",
     "docs:api": "npm run build:docs",
-    "docs:site": "cd docs-site && npm install && npm run build",
-    "docs:serve": "cd docs-site && npm run start",
+    "docs:site": "cd docs-root/guide && npm install && npm run build",
+    "docs:serve": "cd docs-root/guide && npm run start",
     "docs:build": "npm run docs:api && npm run docs:site",
-    "docs:clean": "rimraf docs docs-site/build docs-site/docs/api",
+    "docs:clean": "rimraf docs-root/api docs-root/guide/build",
     "test": "npm run test:unit",
     "test:unit": "jest --config jest.unit.config.js",
     "test:integration": "jest --config jest.integration.config.js",
@@ -88,8 +88,9 @@
     "rimraf": "^5.0.5",
     "ts-jest": "^29.1.2",
     "tsup": "^8.0.2",
-    "typedoc": "^0.25.12",
-    "typedoc-plugin-markdown": "^3.17.1",
+    "typedoc": "^0.28.12",
+    "typedoc-material-theme": "^1.4.0",
+    "typedoc-plugin-markdown": "^4.8.1",
     "typescript": "^5.4.2"
   },
   "peerDependencies": {

package/src/index.ts

@@ -13,7 +13,6 @@ export * from './types';
 export { CX2Network } from './models/CX2Network';
 
 // Core Services
-export { HTTPService } from './services/HTTPService';
 export { NetworkServiceV2 } from './services/NetworkServiceV2';
 export { NetworkServiceV3 } from './services/NetworkServiceV3';
 export { UnifiedNetworkService } from './services/UnifiedNetworkService';
@@ -203,5 +202,29 @@ export class NDExClient {
 
 // 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/services/HTTPService.ts

@@ -20,6 +20,7 @@ import { version } from '../../package.json';
  * 
  * @note User-Agent header is set to 'NDEx-JS-Client/${version}' but only works in Node.js.
  *       Browsers will ignore custom User-Agent headers for security reasons.
+ * @internal
  */
 export class HTTPService {
   private axiosInstance: AxiosInstance;
@@ -163,7 +164,7 @@ export class HTTPService {
   }
 
 
-  /**
+  /*
    * Upload a file to the NDEx API with progress tracking support
    * 
    * This method handles file uploads using multipart/form-data encoding and supports
@@ -177,14 +178,11 @@ export class HTTPService {
    *   - `Buffer` (Node.js): Binary data as Buffer for server-side uploads
    *   - `string`: Text content that will be converted to Blob (useful for CX/CX2 JSON)
    * @param options - Upload configuration options
-   * @param options.filename - Custom filename for the upload. Defaults:
-   *   - File objects: uses `file.name`
-   *   - Other types: 'file.cx2'
+   *
    * @param options.contentType - MIME type for string content (default: 'application/json')
    * @param options.onProgress - Progress callback that receives percentage (0-100)
    *   Called periodically during upload with current progress
    * @param options.version - API version to use ('v2' or 'v3', defaults to 'v2')
-   * @param options.config - Additional Axios configuration options
    * 
    * @returns Promise resolving to upload result
    * 
@@ -226,27 +224,26 @@ export class HTTPService {
     endpoint: string,
     file: File | Blob | Buffer | string,
     options: {
-      filename?: string;
       contentType?: string;
       onProgress?: (progress: number) => void;
       version?: 'v2' | 'v3';
     } = {}
   ): Promise<T> {
-    const { version, onProgress, filename, contentType, ...config } = options;
+    const { version, onProgress, contentType, ...config } = options;
     const url = this.buildUrl(endpoint, version);
 
     const formData = new FormData();
     
     if (file instanceof File) {
-      formData.append('file', file, filename || file.name);
+      formData.append('file', file, file.name);
     } else if (file instanceof Blob) {
-      formData.append('file', file, filename || 'file.cx2');
+      formData.append('file', file, 'file.cx2');
     } else if (typeof file === 'string') {
       const blob = new Blob([file], { type: contentType || 'application/json' });
-      formData.append('file', blob, filename || 'file.cx2');
+      formData.append('file', blob,'file.cx2');
     } else {
       // Buffer (Node.js environment)
-      formData.append('file', file as any, filename || 'file.cx2');
+      formData.append('file', file as any, 'file.cx2');
     }
 
     try {

package/src/services/NetworkServiceV3.ts

@@ -5,7 +5,8 @@ import {
   SearchParameters, 
   PaginationParams,
   AccessParams,
-  CX2Network as CX2NetworkType
+  CX2Network as CX2NetworkType,
+  NDExObjectUpdateStatus
 } from '../types';
 import { CX2Network } from '../models/CX2Network';
 
@@ -199,14 +200,14 @@ export class NetworkServiceV3 {
    */
   async createNetworkFromCX2(
     cx2Data: CX2NetworkType | CX2Network, 
-    options: { visibility?: 'PUBLIC' | 'PRIVATE'; name?: string } = {}
-  ): Promise<{ uuid: string }> {
-    const endpoint = 'networks/cx2';
+    options: { visibility?: 'PUBLIC' | 'PRIVATE'; folderId?: string } = {}
+  ): Promise<NDExObjectUpdateStatus> {
+    const endpoint = 'networks';
     
     // Convert CX2Network object to plain object if needed
     const data = cx2Data instanceof CX2Network ? JSON.parse(cx2Data.toJSON()) : cx2Data;
     
-    return this.http.post<{ uuid: string }>(endpoint, data, { 
+    return this.http.post<NDExObjectUpdateStatus>(endpoint, data, { 
       version: 'v3',
       params: options
     });
@@ -218,13 +219,13 @@ export class NetworkServiceV3 {
   async updateNetworkCX2(
     networkUUID: string, 
     cx2Data: CX2NetworkType | CX2Network
-  ): Promise<void> {
-    const endpoint = `networks/${networkUUID}/cx2`;
+  ): Promise<NDExObjectUpdateStatus> {
+    const endpoint = `networks/${networkUUID}`;
     
     // Convert CX2Network object to plain object if needed
     const data = cx2Data instanceof CX2Network ? JSON.parse(cx2Data.toJSON()) : cx2Data;
     
-    return this.http.put<void>(endpoint, data, { version: 'v3' });
+    return this.http.put<NDExObjectUpdateStatus>(endpoint, data, { version: 'v3' });
   }
 
   /**

package/src/services/UnifiedNetworkService.ts

@@ -9,7 +9,8 @@ import {
   CX2Edge,
   CX1Edge,
   CX2MetaData,
-  NetworkPermission
+  NetworkPermission,
+  NDExObjectUpdateStatus
 } from '../types';
 import { CX2Network } from '../models/CX2Network';
 
@@ -573,47 +574,34 @@ export class UnifiedNetworkService {
   /**
    * Create network from raw CX2 data (migrated from original NDEx.js)
    * 
-   * Creates a new network in NDEx from raw CX2 network data. This is an unstable function
-   * for uploading CX2 format networks directly to NDEx using the V3 API. The function
-   * extracts the network UUID from the response location header.
+   * Creates a new network on NDEx from raw CX2 data using the V3 API.
+   * This function delegates to the NetworkServiceV3 implementation.
    * 
-   * @param rawCX2 - Raw CX2 network data as an object or CX2Network instance
-   * @param makePublic - Whether to make the network public (default: false = private)
-   * @returns Promise resolving to an object containing the UUID of the created network
+   * @param cx2Data - Raw CX2 network data as an object or CX2Network instance
+   * @param options - Creation options including visibility and folderId
+   * @param options.visibility - Network visibility: 'PUBLIC' or 'PRIVATE' (default: 'PRIVATE')
+   * @param options.folderId - UUID of the folder to create the network in. If omitted, network is created in user's home directory
+   * @returns Promise resolving to NDExObjectUpdateStatus with uuid and modificationTime
    * 
    * @example
    * ```typescript
-   * // Create private network from raw CX2 data
+   * // Create private network from raw CX2 data in user's home directory
    * const result = await client.networks.createNetworkFromRawCX2(cx2Data);
    * console.log(result.uuid); // "12345678-1234-1234-1234-123456789abc"
    * 
-   * // Create public network from raw CX2 data
-   * const publicResult = await client.networks.createNetworkFromRawCX2(cx2Data, true);
+   * // Create public network from raw CX2 data in a specific folder
+   * const publicResult = await client.networks.createNetworkFromRawCX2(cx2Data, { 
+   *   visibility: 'PUBLIC', 
+   *   folderId: '87654321-4321-4321-4321-876543210fed'
+   * });
    * console.log(publicResult.uuid);
    * ```
    */
   async createNetworkFromRawCX2(
-    rawCX2: CX2NetworkType | any,
-    makePublic: boolean = false
-  ): Promise<{ uuid: string }> {
-    const params = {
-      visibility: makePublic ? 'PUBLIC' as const : 'PRIVATE' as const
-    };
-
-    const endpoint = 'networks';
-    const response = await this.http.post<string>(endpoint, rawCX2, { 
-      version: 'v3',
-      params 
-    });
-
-    // Extract UUID from response location header (e.g., "/v3/networks/12345" -> "12345")
-    const uuid = response.split('/').pop();
-    
-    if (!uuid) {
-      throw new Error('Failed to extract network UUID from response');
-    }
-    
-    return { uuid };
+    cx2Data: CX2NetworkType | CX2Network,
+    options: { visibility?: 'PUBLIC' | 'PRIVATE'; folderId?: string } = {}
+  ): Promise<NDExObjectUpdateStatus> {
+    return this.v3.createNetworkFromCX2(cx2Data, options);
   }
 
   /**

package/src/types/index.ts

@@ -513,3 +513,12 @@ export interface AccessKeyResponse {
  */
 export type AccessKeyAction = 'enable' | 'disable';
 
+/**
+ * NDEx object update status - returned from network creation and update operations
+ * Corresponds to server-side NdexObjectUpdateStatus class
+ */
+export interface NDExObjectUpdateStatus {
+  uuid: string;
+  modificationTime: number; // Timestamp in milliseconds
+}
+