Class FilesService

FilesService - NDEx file operations and task management Handles file uploads, downloads, exports, and asynchronous task tracking

Constructors

constructor

new FilesService(http: HTTPService): FilesService
Parameters
- http: HTTPService
Returns FilesService
- Defined in services/FilesService.ts:140

Methods

copyFile

copyFile(
    options: {
        fileId: string;
        targetId: string;
        type: NDExFileType;
        accessKey?: string;
    },
): Promise<NDExObjectUpdateStatus>
Copy a file to a different location

Copies a network or shortcut to a target folder. Folder copying is not supported. The copied file will be placed in the specified target folder with the same name and properties as the original.
Parameters
- options: { fileId: string; targetId: string; type: NDExFileType; accessKey?: string }
  Copy operation configuration
  - fileId: string
    UUID of the source file to copy
  - targetId: string
    UUID of the target folder where the file will be copied
  - type: NDExFileType
    Type of file being copied (only NETWORK and SHORTCUT are supported)
  - OptionalaccessKey?: string
    Optional access key for accessing protected files
Returns Promise<NDExObjectUpdateStatus>
Promise resolving to the copied file's UUID and modification time
Example
```
// Copy a network to a specific folder
await client.files.copyFile({
  fileId: "12345678-1234-1234-1234-123456789abc",
  targetId: "87654321-4321-4321-4321-876543210fed",
  type: "NETWORK"
});

// Copy a shortcut with access key
await client.files.copyFile({
  fileId: "11111111-2222-3333-4444-555555555555",
  targetId: "66666666-7777-8888-9999-000000000000",
  type: "SHORTCUT",
  accessKey: "secret-key-123"
});
```
- Defined in services/FilesService.ts:174

getCount

getCount(): Promise<any>
Get file count statistics for the current user

Returns Promise<any>
- Defined in services/FilesService.ts:202

getTrash

getTrash(): Promise<any>
Get files in the trash for the current user

Returns Promise<any>
- Defined in services/FilesService.ts:207

emptyTrash

emptyTrash(): Promise<any>
Permanently delete all files in trash

Returns Promise<any>
- Defined in services/FilesService.ts:212

permanentlyDeleteFile

permanentlyDeleteFile(fileId: string): Promise<any>
Permanently delete a file from trash
Parameters
- fileId: string
  File UUID to permanently delete
Returns Promise<any>
- Defined in services/FilesService.ts:220

restoreFile

restoreFile(
    networkIds: string[],
    folderIds: string[],
    shortcutIds: string[],
): Promise<any>
Restore files from trash
Parameters
- networkIds: string[]
  Array of network UUIDs to restore
- folderIds: string[]
  Array of folder UUIDs to restore
- shortcutIds: string[]
  Array of shortcut UUIDs to restore
Returns Promise<any>
- Defined in services/FilesService.ts:230

updateMember

updateMember(request: SharingMemberRequest): Promise<Record<string, string>>
Update member permissions for shared files

This method allows you to grant, modify, or revoke permissions for specific members across multiple files in a single operation. It's particularly useful for bulk permission management and ensuring consistent access control.
Parameters
- request: SharingMemberRequest
  The sharing member request containing files and member permissions
  
  Request object for sharing member operations
  
  This interface defines the structure for requests that manage file sharing permissions. It combines file identification with member permission management in a single request.
  - files: Record<string, NDExFileType>
    Object mapping file UUIDs to their corresponding file types
    
    Description
    Each key represents the UUID of a file to be shared, and the value indicates what type of file it is (NETWORK, FOLDER, or SHORTCUT)
    
    Example
    { "12345678-1234-1234-1234-123456789abc": "NETWORK", "87654321-4321-4321-4321-876543210fed": "FOLDER" }
  - members: Record<string, Permission | null>
    Object mapping member UUIDs to their permission levels
    
    Description
    Each key represents the UUID of a user or member who should receive explicit permissions, and the value is the type of permission they should have. If the permission value is null, the existing file permission for the member will be revoked.
    
    Example
    { "user1-uuid-1234-5678-9abc-def012345678": "READ", "user2-uuid-8765-4321-fedc-ba0987654321": "WRITE", "user3-uuid-1111-2222-3333-444444444444": null // This will revoke permissions }
Returns Promise<Record<string, string>>
Promise resolving to an object with file UUIDs as keys and permission status messages as values
Example
```
// Grant permissions to multiple members for different files
const result = await client.files.updateMember({
  files: {
    "network-uuid-123": "NETWORK",
    "folder-uuid-456": "FOLDER"
  },
  members: {
    "user1-uuid": "READ",
    "user2-uuid": "WRITE",
    "user3-uuid": null // Revoke permissions
  }
});

// Result example:
// {
//   "network-uuid-123": "network permission granted",
//   "folder-uuid-456": "folder permission granted"
// }

// Revoke all permissions for a user
await client.files.updateMember({
  files: {
    "network-uuid-789": "NETWORK"
  },
  members: {
    "user-to-remove-uuid": null
  }
});
```
Throws
When file UUIDs have invalid format

Throws
When file types are invalid

Throws
When member UUIDs have invalid format
- Defined in services/FilesService.ts:319

listMembers

listMembers(files: Record<string, NDExFileType>): Promise<FilePermissionList>

List members and their permissions for specified files

Retrieves detailed permission information for the specified files, including the file type and a mapping of all users who have explicit permissions on each file. This is useful for auditing file access and understanding who has what level of access to your shared content.

Parameters

files: Record<string, NDExFileType>
Object mapping file UUIDs to their file types

Returns Promise<FilePermissionList>

Promise resolving to a list of permission records for each file

Example

// Get permission details for multiple files
const permissions = await client.files.listMembers({
  "12345678-1234-1234-1234-123456789abc": "NETWORK",
  "87654321-4321-4321-4321-876543210fed": "FOLDER",
  "11111111-2222-3333-4444-555555555555": "SHORTCUT"
});

// Result example:
// [
//   {
//     "12345678-1234-1234-1234-123456789abc": {
//       type: "NETWORK",
//       members: {
//         "user1-uuid-1234-5678-9abc-def012345678": "READ",
//         "user2-uuid-8765-4321-fedc-ba0987654321": "WRITE",
//         "user3-uuid-1111-2222-3333-444444444444": "ADMIN"
//       }
//     }
//   },
//   {
//     "87654321-4321-4321-4321-876543210fed": {
//       type: "FOLDER",
//       members: {
//         "user4-uuid-aaaa-bbbb-cccc-dddddddddddd": "ADMIN",
//         "user5-uuid-eeee-ffff-0000-111111111111": "READ"
//       }
//     }
//   }
// ]

// Access specific file permissions
const networkPermissions = permissions.find(record =>
  record["12345678-1234-1234-1234-123456789abc"]
)?.["12345678-1234-1234-1234-123456789abc"];

if (networkPermissions) {
  console.log('File type:', networkPermissions.type); // "NETWORK"
  console.log('Members:', networkPermissions.members);

  // Check if specific user has permission
  const userPermission = networkPermissions.members["user1-uuid-1234-5678-9abc-def012345678"];
  console.log('User permission:', userPermission); // "READ"
}

Throws

When file UUIDs have invalid format

Throws

When file types are invalid

transferOwnership

transferOwnership(
request: { networks: string[]; newOwner: string },
): Promise<void>
Transfer ownership of networks to a new owner

This method transfers ownership of multiple networks to a specified user. The current owner will lose ownership rights, and the new owner will gain full control over the specified networks.
Parameters
- request: { networks: string[]; newOwner: string }
  Transfer ownership request
  - networks: string[]
    Array of network UUIDs to transfer ownership for
  - newOwner: string
    UUID of the user who will become the new owner
Returns Promise<void>
Promise that resolves when the ownership transfer is complete
Example
```
// Transfer ownership of multiple networks to a new owner
await client.files.transferOwnership({
  networks: [
    "12345678-1234-1234-1234-123456789abc",
    "87654321-4321-4321-4321-876543210fed"
  ],
  newOwner: "new-owner-uuid-1111-2222-3333-444444444444"
});
```
- Defined in services/FilesService.ts:415

listShares

listShares(limit?: number): Promise<FileListItem[]>
Parameters
- Optionallimit: number
Returns Promise<FileListItem[]>
- Defined in services/FilesService.ts:419

share(fileTable: Record<string, NDExFileType>): Promise<Record<string, string>>
Share files with public access

Makes specified files publicly accessible by generating access keys for each file. The generated access keys can be used by others to access the shared files without requiring explicit permissions.
Parameters
- fileTable: Record<string, NDExFileType>
  Object mapping file UUIDs to their file types
Returns Promise<Record<string, string>>
Promise resolving to an object mapping file UUIDs to their generated access keys
Example
```
// Share a network and a folder
const result = await client.files.share({
  "e6fc6a72-59ea-4f1d-ad81-59eda2cb8dce": "NETWORK",
  "40c08b7b-a4dd-4f00-87b3-1b945991948a": "FOLDER"
});

// Result example:
// {
//   "e6fc6a72-59ea-4f1d-ad81-59eda2cb8dce": "abc123def456",
//   "40c08b7b-a4dd-4f00-87b3-1b945991948a": "xyz789uvw012"
// }

// Use the access key to access shared content
const sharedNetwork = await client.networks.getNetwork(
  "e6fc6a72-59ea-4f1d-ad81-59eda2cb8dce",
  { accessKey: result["e6fc6a72-59ea-4f1d-ad81-59eda2cb8dce"] }
);
```
- Defined in services/FilesService.ts:458

unshare

unshare(fileTable: Record<string, NDExFileType>): Promise<void>
Parameters
- fileTable: Record<string, NDExFileType>
Returns Promise<void>
- Defined in services/FilesService.ts:463

getFolders

getFolders(limit?: number): Promise<any>
Parameters
- Optionallimit: number
Returns Promise<any>
- Defined in services/FilesService.ts:469

createFolder

createFolder(name: string, parentFolderId?: string): Promise<any>
Parameters
- name: string
- OptionalparentFolderId: string
Returns Promise<any>
- Defined in services/FilesService.ts:478

getFolder

getFolder(folderId: string, accessKey?: string): Promise<any>
Parameters
- folderId: string
- OptionalaccessKey: string
Returns Promise<any>
- Defined in services/FilesService.ts:482

updateFolder

updateFolder(
folderId: string,
folderData: { name: string; description: string; parent?: string },
): Promise<void>
Update folder properties

Updates the properties of an existing folder including name, description, and parent location. When parent is omitted, the folder remains in or is moved to the owner's home directory.
Parameters
- folderId: string
  The UUID of the folder to update
- folderData: { name: string; description: string; parent?: string }
  Object containing folder properties to update
  - name: string
    The new name for the folder
  - description: string
    The new description for the folder
  - Optionalparent?: string
    Optional UUID of the parent folder. If omitted, folder is placed in owner's home directory
Returns Promise<void>
Promise that resolves when the folder update is complete
Example
```
// Update folder name and description, keep in current location
await client.files.updateFolder('folder-uuid', {
  name: 'Updated Folder Name',
  description: 'Updated folder description'
});

// Move folder to a different parent and update properties
await client.files.updateFolder('folder-uuid', {
  name: 'Moved Folder',
  description: 'This folder has been moved',
  parent: 'parent-folder-uuid'
});

// Move folder to home directory by omitting parent
await client.files.updateFolder('folder-uuid', {
  name: 'Home Folder',
  description: 'Moved to home directory'
});
```
- Defined in services/FilesService.ts:525

deleteFolder

deleteFolder(folderId: string): Promise<any>
Parameters
- folderId: string
Returns Promise<any>
- Defined in services/FilesService.ts:536

getFolderCount

getFolderCount(folderId: string, accessKey?: string): Promise<any>
Parameters
- folderId: string
- OptionalaccessKey: string
Returns Promise<any>
- Defined in services/FilesService.ts:540

getFolderList

getFolderList(
    folderId: string,
    accessKey?: string,
    format?: string,
    type?: string,
): Promise<FileListItem[]>
Parameters
- folderId: string
- OptionalaccessKey: string
- Optionalformat: string
- Optionaltype: string
Returns Promise<FileListItem[]>
- Defined in services/FilesService.ts:548

getFolderAccessKey

getFolderAccessKey(folderId: string): Promise<null | { accessKey: string }>
Get folder access key

Retrieves the access key for a folder if it has been enabled for public access. When a folder has an access key enabled, it can be accessed by others without explicit permissions using this key.
Parameters
- folderId: string
  The UUID of the folder to get the access key for
Returns Promise<null | { accessKey: string }>
Promise resolving to an object with accessKey property when enabled, or null when access key is not enabled on this folder
Example
```
// Check if folder has an access key
const result = await client.files.getFolderAccessKey('12345678-1234-1234-1234-123456789abc');

if (result) {
  console.log('Access key:', result.accessKey); // "sdfdfdfsdfdsfs"
  // Use the access key to access the folder
  const folderData = await client.files.getFolder(folderId, result.accessKey);
} else {
  console.log('No access key enabled for this folder');
}
```
- Defined in services/FilesService.ts:587

getShortcuts

getShortcuts(limit?: number): Promise<any>
Parameters
- Optionallimit: number
Returns Promise<any>
- Defined in services/FilesService.ts:593

createShortcut

createShortcut(options: CreateShortcutOptions): Promise<NDExObjectUpdateStatus>
Create a shortcut to an existing NDEx object

Creates a shortcut (reference) to an existing network, folder, or shortcut. The shortcut can be placed in a specific folder or in the user's home directory.
Parameters
- options: CreateShortcutOptions
  Shortcut creation options
  - name
    Display name for the shortcut
  - target
    UUID of the target object to create a shortcut to
  - targetType
    Type of the target object ('NETWORK', 'FOLDER', or 'SHORTCUT')
  - parent
    Optional UUID of the parent folder. If omitted, shortcut is created in user's home directory
Returns Promise<NDExObjectUpdateStatus>
Promise resolving to the created shortcut information
Example
```
// Create shortcut to a network in home directory
await client.files.createShortcut({
  name: "My Important Network Shortcut",
  target: "12345678-1234-1234-1234-123456789abc",
  targetType: "NETWORK"
});

// Create shortcut to a folder within another folder
await client.files.createShortcut({
  name: "Research Folder Shortcut",
  target: "87654321-4321-4321-4321-876543210fed",
  targetType: "FOLDER",
  parent: "11111111-2222-3333-4444-555555555555"
});
```
- Defined in services/FilesService.ts:633

getShortcut

getShortcut(shortcutId: string, accessKey?: string): Promise<Shortcut>
Parameters
- shortcutId: string
- OptionalaccessKey: string
Returns Promise<Shortcut>
- Defined in services/FilesService.ts:637

updateShortcut

updateShortcut(
shortcutId: string,
shortcutObject: CreateShortcutOptions,
): Promise<any>
Update shortcut properties

Updates the properties of an existing shortcut including name, parent location, target, and target type. The parent attribute is always included in the request payload - when parent is omitted from the shortcut object, parent is set to null to indicate the shortcut should be moved to the owner's home directory.
Parameters
- shortcutId: string
  The UUID of the shortcut to update
- shortcutObject: CreateShortcutOptions
  Object containing shortcut properties to update
  - name
    The new name for the shortcut
  - target
    UUID of the target object the shortcut points to
  - targetType
    Type of the target object ('NETWORK', 'FOLDER', or 'SHORTCUT')
  - parent
    Optional UUID of the parent folder. If omitted, shortcut is moved to home directory
Returns Promise<any>
Promise resolving when the shortcut update is complete
Example
```
// Update shortcut name and target, move to home directory
await client.files.updateShortcut('shortcut-uuid', {
  name: 'Updated Shortcut Name',
  target: 'target-network-uuid',
  targetType: 'NETWORK'
});

// Update shortcut and move to a specific folder
await client.files.updateShortcut('shortcut-uuid', {
  name: 'Folder Shortcut',
  target: 'target-folder-uuid',
  targetType: 'FOLDER',
  parent: 'parent-folder-uuid'
});

// Update all shortcut properties
await client.files.updateShortcut('shortcut-uuid', {
  name: 'Complete Update',
  target: 'target-network-uuid',
  targetType: 'NETWORK',
  parent: 'parent-folder-uuid'
});
```
- Defined in services/FilesService.ts:686

deleteShortcut

deleteShortcut(shortcutId: string): Promise<any>
Parameters
- shortcutId: string
Returns Promise<any>
- Defined in services/FilesService.ts:693

setVisibility

setVisibility(
options: { files: Record<string, NDExFileType>; visibility: Visibility },
): Promise<void>
Set visibility for multiple files

Updates the visibility settings for the specified files, controlling who can access them based on the visibility level (public, private, etc.).
Parameters
- options: { files: Record<string, NDExFileType>; visibility: Visibility }
  Visibility update configuration
  - files: Record<string, NDExFileType>
    Object mapping file UUIDs to their file types
  - visibility: Visibility
    The visibility level to apply to all specified files
Returns Promise<void>
Promise that resolves when the visibility has been updated
Example
```
// Make multiple files public
await client.files.setVisibility({
  files: {
    "12345678-1234-1234-1234-123456789abc": "NETWORK",
    "87654321-4321-4321-4321-876543210fed": "FOLDER"
  },
  visibility: "PUBLIC"
});
```
- Defined in services/FilesService.ts:720

searchFiles

searchFiles(params: FileSearchParams): Promise<FileSearchResult>
Search for files in NDEx

Searches files using the server's SimpleFileQuery request body and pagination query parameters. The query object can filter by search text, owner, permission, and file type, while visibility is sent separately as a required URL parameter. Results are returned in a paginated object with numFound, start, and a files array.
Parameters
- params: FileSearchParams
  Search parameters
  
  Parameters for searching files in NDEx
  - OptionalsearchString?: string
    Search terms as a string, supports Lucene syntax
  - OptionalaccountName?: string
    Username of the account to filter on, only files owned by that user will be returned
  - Optionalpermission?: Permission
    Filter by permission level, only applicable to signed-in users
  - Optionaltype?: null | NDExFileType
    File type to filter on, if null or omitted all file types will be returned
  - visibility: "PUBLIC" | "PRIVATE"
    Visibility filter, only supports "PRIVATE" or "PUBLIC"
  - Optionalstart?: number
    Starting index for pagination
  - Optionalsize?: number
    Number of results to return for pagination
Returns Promise<FileSearchResult>
Promise resolving to a paginated search result containing matching files
Example
```
// Search for public networks containing "cancer"
const results = await client.files.searchFiles({
  searchString: "cancer",
  type: "NETWORK",
  visibility: "PUBLIC",
  start: 0,
  size: 25
});

console.log(`Found ${results.numFound} total results`);
console.log(`Showing results starting at ${results.start}`);
results.files.forEach(file => {
  console.log(`${file.name} (${file.type})`);
});

// Search for public networks owned by a specific user
const userNetworks = await client.files.searchFiles({
  searchString: "name:pathway AND description:signaling",
  accountName: "john_doe",
  type: "NETWORK",
  visibility: "PUBLIC"
});

// Search for private files the signed-in user can write to
const writableFiles = await client.files.searchFiles({
  permission: "WRITE",
  visibility: "PRIVATE",
  start: 0,
  size: 50
});
```
- Defined in services/FilesService.ts:778

Class FilesService

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns FilesService

Methods

copyFile

Parameters

fileId: string

targetId: string

type: NDExFileType

OptionalaccessKey?: string

Returns Promise<NDExObjectUpdateStatus>

Example

getCount

Returns Promise<any>

getTrash

Returns Promise<any>

emptyTrash

Returns Promise<any>

permanentlyDeleteFile

Parameters

Returns Promise<any>

restoreFile

Parameters

Returns Promise<any>

updateMember

Parameters

files: Record<string, NDExFileType>

Description

Example

members: Record<string, Permission | null>

Description

Example

Returns Promise<Record<string, string>>

Example

Throws

Throws

Throws

listMembers

Parameters

Returns Promise<FilePermissionList>

Example

Throws

Throws

transferOwnership

Parameters

networks: string[]

newOwner: string

Returns Promise<void>

Example

listShares

Parameters

Returns Promise<FileListItem[]>

share

Parameters

Returns Promise<Record<string, string>>

Example

unshare

Parameters

Returns Promise<void>

getFolders

Parameters

Returns Promise<any>

createFolder

Parameters

Returns Promise<any>

getFolder

Parameters

Returns Promise<any>

updateFolder

Parameters

name: string

description: string

Optionalparent?: string

Returns Promise<void>

Example

`Optional`accessKey?: string

`Optional`parent?: string

`Optional`searchString?: string

`Optional`accountName?: string

`Optional`permission?: Permission

`Optional`type?: null | NDExFileType

`Optional`start?: number

`Optional`size?: number