@trimblecloudplatform/trimblecloud-fileservice

FileService SDK for Typescript. Trimble File Service provides capabilities for managing file type of resources organized into folders and related metadata in a secure way with predefined ACL roles.

Installation

This SDK is available as a npm package in Trimble Artifactory. To install, use the following command:

npm install @trimblecloudplatform/trimblecloud-fileservice

FileService Endpoints

These are the US region endpoints for File Service:

Environment	Base URL Endpoint
Stage	https://cloud.stage.api.trimblecloud.com/fileservice/api/2.0
Production	https://cloud.api.trimble.com/fileservice/api/2.0

For other regions, refer to the Trimble Cloud Console.

Create FileService Client

To create a FileServiceClient, you need to provide a token provider and the File Service endpoint. The token provider is used to authenticate the client with Trimble Identity (TID).

For more details on token providers, refer to the Trimble Identity JS/TS SDK Documentation.

import { FixedTokenProvider } from '@trimble-oss/trimble-id';

import { FileServiceClient } from '@trimblecloudplatform/trimblecloud-fileservice';

// Create a token provider
let tokenProvider = FixedTokenProvider("<ACCESS_TOKEN>");

// Create a FileService client
var client = new FileServiceClient(tokenProvider, '<FILESERVICE_ENDPOINT>');

Minimal Response Feature

• The minimal response feature provides a streamlined version of response data by including only essential attributes of an entity.
• This reduces the response size, leading to faster data transfer and lower bandwidth usage.
• It is particularly useful when the client does not need all the attributes of an entity.
• The minimal response feature is applicable for all synchronous operation responses, including methods such as Create, Get, Update, Move, Rename, Restore, Lock, Unlock, GetVersion and List methods.

NOTE: By default, all operations return a complete response. If you need a minimal response, you can specify the minimalResponse parameter as true in the method call.

Spaces

A space is a container for files and folders. It is the top-level entity in the file service. A root folder is created automatically when a space is created.

Create

Create a new space.

let params: SpaceCreateOptionalParams = {
        provider: Provider.AZURE,
        permissionsLocal: {
            acl: [
                {
                    role: AclRole.SpaceManager,
                    actor: "trn:tid:application:<uuid>"
                },
                {
                    role: AclRole.ContentManager,
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }

    }
let space : SpaceResponse = await client.spaces.create('<SPACE_NAME>','<ACCOUNT_ID>', params)

Create a new space and return a minimal response.

let params : SpaceCreateOptionalParams = { provider: Provider.AZURE }
let space : MinimalSpaceResponse = await client.spaces.create('<SPACE_NAME>','<ACCOUNT_ID>', params, true)

Get

Get space descriptor by ID.

let space : SpaceResponse = await client.spaces.get('<SPACE_ID>')

Get space by ID with a minimal response.

let result : MinimalSpaceResponse = await client.spaces.get("<SPACE_ID>", true)

Update

Update space descriptor by ID. Only the name and acl details can be updated for the given space.

Replace existing permissions with the provided permissions

let params: SpaceUpdateParams = {
    name: "test_space_name_updated",
    permissionsLocal: {
        acl: [
                {
                    actor: "trn:tid:application:<uuid>",
                    role: AclRole.ContentViewer
                }
            ]
    }
}

let space : SpaceResponse = await client.spaces.update('<SPACE_ID>', params)

Actors can be added or removed from the existing permissions

let params: SpaceUpdateParams = {
    name: "test_space_name_updated",
    permissionsLocal: {
        updateAcl: {
            add: [
                {
                    actor: "trn:tid:application:<uuid>",
                    role: AclRole.ContentViewer
                }
            ],
            remove: [
                {
                    actor: "trn:tid:application:<uuid>",
                    role: AclRole.ContentManager
                }
            ]
        }
    }
}

let space : SpaceResponse = await client.spaces.update('<SPACE_ID>', params)

Update space by ID and return a minimal response.

let params : SpaceUpdateParams = { name: 'test_space_name_updated'}
let space : MinimalSpaceResponse = await client.spaces.update('<SPACE_ID>', params, true)

Delete

Delete space by Id. By default, it is a soft delete operation.

let deleteResponse : SpaceDeleteResponse =  await client.spaces.delete('<SPACE_ID>')

The delete operation’s response has the Job ID for non empty space deletion.

To delete a non empty space, set recursive field to true

let deleteParams : SpaceDeleteOptionalParams = {recursive : true}
let result = await client.spaces.delete('<SPACE_ID>', { recursive: true })

Restore

Restore a space from the deleted state.

let result: SpaceRestoreResponse = await client.spaces.restore('<SPACE_ID>')

Restore a space and return a minimal response.

let result: SpaceRestoreResponse = await client.spaces.restore('<SPACE_ID>', true)

List Children

List child resources of a space by ID. Returns the resources of the space including itself, the root folder, and its children (files and folders).

let result: SpaceListResponse = await client.spaces.list('<SPACE_ID>')

List children of a space with optional parameters to filter the results.

let params: SpaceListOptionalParams = {
    pageSize: 10,
    status: 'active',
    resourceType: EntityType.FILE,
    supportFiles: true
}
let result: SpaceListResponse = await client.spaces.list('<SPACE_ID>', { params })

List children of a space with minimal response for bandwidth optimization.

let result: SpaceListResponse = await client.spaces.list('<SPACE_ID>', { minimalResponse: true })

List children of a space with parameters and minimal response.

let params: SpaceListOptionalParams = {
    pageSize: 20,
    status: 'active,deleted',
    sinceTime: new Date('2024-01-01')
}
let result: SpaceListResponse = await client.spaces.list('<SPACE_ID>', { params, minimalResponse: true })

List children of a space with additional request headers and options.

let params: SpaceListOptionalParams = {
    pageSize: 10,
    resourceType: EntityType.FOLDER,
    sortOrder: 'lastModified:desc'
}
let headers = { "If-Match": "1.3" }
let result: SpaceListResponse = await client.spaces.list('<SPACE_ID>', {
    params,
    minimalResponse: false,
    requestHeaders: headers
})

Folders

A folder is a container for files and other folders.

Create

Create a new folder under the given parentId.

let params: FolderCreateOptionalParams = {
    metadata: { key: "value" },
    permissionsLocal: {
        inherits: false,
        acl: [
            {
                actor: "trn:tid:application:<uuid>",
                role: AclRole.ContentManager
            },
        ]
    }
}

let folder : FolderResponse = await client.folders.create('<SPACE_ID>','<PARENT_ID>','<FOLDER_NAME>', params)

Create a new folder under the given parentId and return a minimal response.

let folder : MinimalFolderResponse = await client.folders.create('<SPACE_ID>','<PARENT_ID>','<FOLDER_NAME>', params, true)

Get by Path

Get Folder details for a given folder path.

let folder : FolderResponse = await client.folders.getByPath('<SPACE_ID>','<FOLDER_ID>','<PATH>')

Get Folder details for a given folder path with minimal response.

let folder : MinimalFolderResponse = await client.folders.getByPath('<SPACE_ID>','<FOLDER_ID>','<PATH>', true)

Get

Get Folder details by ID.

let folder : FolderResponse = await client.folders.get('<SPACE_ID>','<FOLDER_ID>')

Get Folder details by ID with minimal response.

let folder : MinimalFolderResponse = await client.folders.get('<SPACE_ID>','<FOLDER_ID>', true)

Update

Update Folder by ID. This operation is used to update the folder custom metadata and ACL settings.

Replace existing permissions with the provided permissions

let params: FolderUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        acl:[
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
}

let folder : FolderResponse = await client.folders.update('<SPACE_ID>','<FOLDER_ID>', params)

Actors can be added or removed from the existing permissions

let params: FolderUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        updateAcl: {
            add: [
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ],
            remove: [
                {
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
    }
}

let folder : FolderResponse = await client.folders.update('<SPACE_ID>','<FOLDER_ID>', params)

Update Folder by Id and return minimal response.

let params : FolderUpdateParams = { metadata : {'key' : 'updated_value'}}
let folder : MinimalFolderResponse = await client.folders.update('<SPACE_ID>','<FOLDER_ID>', params, true)

Update Folder by ID allowing you to pass additional request headers.

let params: FolderUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        acl:[
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
}
let headers = { "If-Match": "1" };
await client.folders.updateWithOptions("<SPACE_ID>", "<FOLDER_ID>", params, { requestHeaders: headers, minimalResponse: true });

Delete

Delete Folder by ID.

let params: FolderDeleteOptionalParams = { permanent: true, recursive: true }
let deleteResponse : FolderDeleteResponse = await client.folders.delete('<SPACE_ID>','<FOLDER_ID>', params)

The delete operation’s response has the Job ID for non empty space deletion.

Delete Folder by ID allowing you to pass additional request headers.

let headers = { "If-Match": "1" };
await client.folders.deleteWithOptions("<SPACE_ID>", "<FOLDER_ID>", { requestHeaders: headers });

Move

Move a folder to a new location within the same space.

let moveResponse : FolderMoveResponse = await client.folders.move('<SPACE_ID>','<FOLDER_ID>','<TARGET_PARENT_ID>')

Move a folder to a new location within the same space and return minimal response.

let moveResponse : FolderMoveResponse = await client.folders.move('<SPACE_ID>','<FOLDER_ID>','<TARGET_PARENT_ID>', true)

Move a folder to a new location within the same space allowing you to pass additional request headers.

let headers = { "If-Match": "1" };
await client.folders.moveWithOptions("<SPACE_ID>", "<FOLDER_ID>", "<TARGET_PARENT_ID>", { requestHeaders: headers, minimalResponse: true });

Rename

Rename a folder with a new name.

let renameResponse : FolderRenameResponse = await client.folders.rename('<SPACE_ID>','<FOLDER_ID>','<NAME>')

Rename a folder with a new name and return a minimal response.

let renameResponse : FolderRenameResponse = await client.folders.rename('<SPACE_ID>','<FOLDER_ID>','<NAME>', true)

Rename a folder with a new name allowing you to pass additional request headers.

let headers = { "If-Match": "1" };
await client.folders.renameWithOptions("<SPACE_ID>", "<FOLDER_ID>", "<NEW_NAME>", { requestHeaders: headers});

Copy

Copy a folder to a new location within the same space.

let params: FolderCopyOptionalParams = {copySupportFiles: true, overwriteExisting: true}
let copyResponse : FolderCopyResponse = await client.folders.copy('<SPACE_ID>','<FOLDER_ID>','<TARGET_PARENT_ID>', params)

Copy a folder to a new location within the same space and return a minimal response.

let params: FolderCopyOptionalParams = {copySupportFiles: true, overwriteExisting: true}
let copyResponse : FolderCopyResponse = await client.folders.copy('<SPACE_ID>','<FOLDER_ID>','<TARGET_PARENT_ID>', params, true)

Copy a folder to a new location within the same space allowing you to pass additional request headers.

let params: FolderCopyOptionalParams = {overwriteExisting: true, copySupportFiles: true}
let headers = { "If-Match": "*" };
let copyResponse = await client.folders.copyWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  "<TARGET_PARENT_ID>",
  { params, requestHeaders: headers }
);

Restore

Restore a folder and its children from the deleted state to their original location.

let params: FolderRestoreOptionalParams = { targetParentId:'<TARGET_PARENT_ID>'}
let folder : FolderRestoreResponse = await client.folders.restore('<SPACE_ID>','<FOLDER_ID>', params)

Restore a deleted folder by ID and return minimal response.

let params: FolderRestoreOptionalParams = { targetParentId:'<TARGET_PARENT_ID>'}
let folder : FolderRestoreResponse = await client.folders.restore('<SPACE_ID>','<FOLDER_ID>', params, true)

Restore a folder and its children from the deleted state to their original location allowing you to pass additional request headers.

let headers = { "If-Match": "1" };
await client.folders.restoreWithOptions("<SPACE_ID>", "<FOLDER_ID>", { params, requestHeaders: headers});

List

Lists all children of a folder in a space by ID.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FileOrFolderListResponse = await client.folders.list('<SPACE_ID>','<FOLDER_ID>', params)

Lists all children of a folder in a space by ID with minimal response.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FileOrFolderListResponse = await client.folders.list('<SPACE_ID>','<FOLDER_ID>', params, true)

Lists all children of a folder with sorting and recursive options.

let params: FolderListOptionalParams = {
    pageSize: 20,
    sortBy: 'name',
    sortOrder: 'asc',
    recursive: 'true'
}
let folders : FileOrFolderListResponse = await client.folders.list('<SPACE_ID>','<FOLDER_ID>', params)

Get Version

Get details for the specified folder version.

let folder : FolderResponse = await client.folders.getVersion('<SPACE_ID>','<FOLDER_ID>','<VERSION_ID>')

Get details for the specified folder version with minimal response.

let folder : MinimalFolderResponse = await client.folders.getVersion('<SPACE_ID>','<FOLDER_ID>','<VERSION_ID>', true)

List all versions

List all versions for a folder in a space by ID.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FolderListResponse = await client.folders.listVersions('<SPACE_ID>','<FOLDER_ID>', params)

List all versions for a folder in a space by ID with minimal response.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FolderListResponse = await client.folders.listVersions('<SPACE_ID>','<FOLDER_ID>', params, true)

List by path

Lists all children of a folder in a space by path.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FileOrFolderListResponse = await client.folders.listByPath('<SPACE_ID>','<PATH>', params)

Lists all children of a folder in a space by path with minimal response.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FileOrFolderListResponse = await client.folders.listByPath('<SPACE_ID>','<PATH>', params, true)

Lists all children of a folder by path with sorting and recursive options.

let params: FolderListOptionalParams = {
    pageSize: 15,
    sortBy: 'updatedAt',
    sortOrder: 'desc',
    recursive: 'false'
}
let folders : FileOrFolderListResponse = await client.folders.listByPath('<SPACE_ID>','<PATH>', params)

Get version by path

Fetch the folder details for the given folder version.

let folder : FolderResponse = await client.folders.getVersionByPath('<SPACE_ID>','<VERSION_ID>','<PATH>')

Fetch the folder details for the given folder version with minimal response.

let folder : MinimalFolderResponse = await client.folders.getVersionByPath('<SPACE_ID>','<VERSION_ID>','<PATH>', true)

List versions by path

List all versions for a folder in a space by path.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FolderListResponse = await client.folders.listVersionsByPath('<SPACE_ID>','<PATH>', params)

List all versions for a folder in a space by path with minimal response.

let params: FolderListOptionalParams = { pageSize: 10 }
let folders : FolderListResponse = await client.folders.listVersionsByPath('<SPACE_ID>','<PATH>', params, true)

Files

A file is a binary object that resides under a folder.

Get by Path

Get file by path.

let file : FileResponse = await client.files.getByPath('<SPACE_ID>','PATH')

Get file by path with minimal response.

let file : MinimalFileResponse = await client.files.getByPath('<SPACE_ID>','PATH', true)

Get

Get file by ID.

let file : FileResponse = await client.files.get('<SPACE_ID>','<FILE_ID>')

Get file by id with minimal response.

let file : MinimalFileResponse = await client.files.get('<SPACE_ID>','<FILE_ID>', true)

Update

Update file by ID. Only the metadata, ACL and links can be updated.

Replace existing permissions with the provided permissions

let params: FileUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        acl:[
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
}

let file : FileResponse = await client.files.update('<SPACE_ID>','<FILE_ID>', params)

Actors can be added or removed from the existing permissions

let params: FileUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        updateAcl: {
            add: [
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ],
            remove: [
                {
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
    }
}

let file : FileResponse = await client.files.update('<SPACE_ID>','<FILE_ID>', params)

Updates the file metadata and return minimal response.

let params : FileUpdateParams = { metadata: {'key': 'updated_value'}}
let file : MinimalFileResponse = await client.files.update('<SPACE_ID>','<FILE_ID>', params, true)

Update file by ID allowing you to pass additional request headers.

let params: FileUpdateParams = {
    metadata: { 'key': 'updated_value' },
    permissionsLocal: {
        acl:[
                {
                    role: AclRole.ContentContributor,
                    actor: "trn:tid:application:<uuid>"
                }
            ]
        }
}
let headers = { "If-Match": "1.3" };
let file = await client.files.updateWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  params,
  { requestHeaders: headers }
);

Delete

Deletes the file. By default, it is a soft delete operation.

let params: FileDeleteOptionalParams = { permanent: true }
const result : FileDeleteResponse = await client.files.delete('<SPACE_ID>','<FILE_ID>', params)

Deletes the file allowing you to pass additional request headers.

let params: FileDeleteOptionalParams = { permanent: true }
let headers = { "If-Match": "1.3" };
let result = await client.files.deleteWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  { requestHeaders: headers, params }
);

Move

Move a file to a new location within the same space.

let file : FileResponse = await client.files.move('<SPACE_ID>','<FILE_ID>','<TARGET_PARENT_ID>')

Move a file to a new location within the same space and return a minimal response.

let file : MinimalFileResponse = await client.files.move('<SPACE_ID>','<FILE_ID>','<TARGET_PARENT_ID>', true)

Move a file to a new location within the same space allowing you to pass additional request headers.

let headers = { "If-Match": "1.3" };
let file = await client.files.moveWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  "<TARGET_PARENT_ID>",
  { requestHeaders: headers, name: "new_name" }
);

Rename

Rename a file within the same space.

let file : FileResponse = await client.files.rename('<SPACE_ID>','<FILE_ID>','<NAME>')

Rename a file within the same space and return a minimal response.

let file : MinimalFileResponse = await client.files.rename('<SPACE_ID>','<FILE_ID>','<NAME>', true)

Rename a file within the same space allowing you to pass additional request headers.

let headers = { "If-Match": "1.3" };
let file = await client.files.renameWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  "<NEW_NAME>",
  { requestHeaders: headers }
);

Copy

Copies a file from one folder to another within the given space.

let params : FileCopyOptionalParams = {overwriteExisting: true, copySupportFiles: true}
let copyResponse : FileCopyResponse = await client.files.copy('<SPACE_ID>','<FILE_ID>','<TARGET_PARENT_ID>', params)

Copies a file from one folder to another within the given space and return minimal response

let params : FileCopyOptionalParams = {overwriteExisting: true, copySupportFiles: true}
let copyResponse : FileCopyResponse = await client.files.copy('<SPACE_ID>','<FILE_ID>','<TARGET_PARENT_ID>', params, true)

Copies a file version

let params : FileCopyOptionalParams = { versionId : "1.3" }
let copyResponse = await client.files.copy("<SPACE_ID>", "<FILE_ID>", "<TARGET_PARENT_ID>", params);

Copies a file from one folder to another within the given space allowing you to pass additional request headers.

let params : FileCopyOptionalParams = {overwriteExisting: true, copySupportFiles: true}
let headers = { "If-Match": "*" };
let copyResponse = await client.files.copyWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  "<TARGET_PARENT_ID>",
  { params, requestHeaders: headers }
);

Restore

Restore a file from the deleted state.

let params: FileRestoreOptionalParams = { targetParentId: '<TARGET_PARENT_ID>' }
let result : FileRestoreResponse = await client.files.restore('<SPACE_ID>','<FILE_ID>', params)

Restore a file from the deleted state and return a minimal response

let params: FileRestoreOptionalParams = { targetParentId: '<TARGET_PARENT_ID>' }
let result : FileRestoreResponse = await client.files.restore('<SPACE_ID>','<FILE_ID>', params, true)

Restore a file from the deleted state allowing you to pass additional request headers.

let params: FileRestoreOptionalParams = { targetParentId: '<TARGET_PARENT_ID>' }
let headers = { "If-Match": "1.3" };
let restoreResponse = await client.files.restoreWithOptions(
  "<SPACE_ID>",
  "<FILE_ID>",
  { params, requestHeaders: headers}
);

Get version

Get a specific version of a file.

let params: FileGetOptionalParams = { status: "active,deleted" }
let file : FileResponse = await client.files.getVersion('<SPACE_ID>','<FILE_ID>','<VERSION_ID>', params)

Get a specific version of a file with minimal response.

let params: FileGetOptionalParams = { status: "active,deleted"}
let file : MinimalFileResponse = await client.files.getVersion('<SPACE_ID>','<FILE_ID>','<VERSION_ID>', params, true)

List versions

Get all versions of a file.

let params: FileListVersionsOptionalParams = { pageSize: 10 }
let files : FileListResponse = await client.files.listVersions('<SPACE_ID>','<FILE_ID>', params)

Get all versions of a file with minimal response.

let params: FileListVersionsOptionalParams = { pageSize: 10 }
let files : FileListResponse = await client.files.listVersions('<SPACE_ID>','<FILE_ID>', params, true)

Get version by path

Get a specific version of a file by path.

let params: FileGetOptionalParams = { status: "active,deleted" }
let file : FileResponse = await client.files.getVersionByPath('<SPACE_ID>','<VERSION_ID>','<PATH>', params)

Get a specific version of a file by path with minimal response.

let params: FileGetOptionalParams = { status: "active,deleted"}
let file : MinimalFileResponse = await client.files.getVersionByPath('<SPACE_ID>','<VERSION_ID>','<PATH>', params, true)

List versions by path

Get all versions of a file by path.

let params: FileListVersionsOptionalParams = { pageSize: 10 }
let files : FileListResponse = await client.files.listVersionsByPath('<SPACE_ID>','<PATH>', params)

Get all versions of a file by path with minimal response.

let params: FileListVersionsOptionalParams = { pageSize: 10 }
let files : FileListResponse = await client.files.listVersionsByPath('<SPACE_ID>','<PATH>', params, true)

List Resources

Lists all resources (support files) of a file by ID.

let params: FileListResourcesOptionalParams = { pageSize: 10 }
let result: FileListResponse = await client.files.listResources('<SPACE_ID>','<FILE_ID>', params)

Lists all resources (support files) of a file by id with minimal response.

let params: FileListResourcesOptionalParams = { pageSize: 10 }
let result: FileListResponse = await client.files.listResources('<SPACE_ID>','<FILE_ID>', params, true)

List Resources by path

Lists all resources (support files) of a file by path.

let params: FileListResourcesOptionalParams = { pageSize: 10 }
let result: FileListResponse = await client.files.listResourcesByPath('<SPACE_ID>','<PATH>', params)

Lists all resources (support files) of a file by path with minimal response.

let params: FileListResourcesOptionalParams = { pageSize: 10 }
let result: FileListResponse = await client.files.listResourcesByPath('<SPACE_ID>','<PATH>', params, true)

Uploads

SDK handles file upload in two ways:

1. Single method that creates the upload and uploads the file to the upload URL (upload()).
2. Two separate methods: One to create the upload (createFileUpload()/createSupportFileUpload()) and another to upload the file (uploadFile()).

Upload

• This method handles both the creation of the upload and the actual file upload in one step.
• Support both multipart and single part methods. @default: Single Part - File uploaded directly to the pre signed url. For multipart uploads, the file is divided and uploaded in segments to pre-signed URLs.
  • maxConcurrentRequests defaults to 4 but can be adjusted.
  • chunkSize is set at 5MB by default (5 * 1024 * 1024 bytes), with a minimum part size of 5MB and a maximum of 5GB.

let headers = { "If-Match": "*" };
let options : UploadOptions = {
        multipart: true,
        chunkSize: 1024 * 1024 * 10,
        maxConcurrentRequests: 5,
        requestHeaders: headers
    }
const fileUploadResponse : UploadResponse = await client.files.upload('<SPACE_ID>','<NAME>','<PARENT_ID>', file_content, options)

Create File Upload

Creates the file upload and returning the file upload URL.

let params: FileUploadCreateOptionalParams = { multipart: true }
let response: FileUploadResponse = await client.files.createFileUpload('<SPACE_ID>', "NAME", '<PARENT_ID>', params)

Creates the file upload and returns the file upload URL, allowing you to pass additional request headers.

let params: FileUploadCreateOptionalParams = { multipart: true };
let headers = { "If-Match": "*" };

let uploadResponse: FileUploadResponse = await client.files.createFileUploadWithOptions(
  "<SPACE_ID>",
  "<NAME>",
  "<PARENT_ID>",
  { params, requestHeaders: headers }
);

Create Support File Upload

This method is responsible for creating the support file upload and returning the support file upload URL.

let params: SupportFileUploadCreateOptionalParams = {
    parentMajorVersion: 1,
    supportFileKey: "KEY",
    multipart: true,
};
let response: SupportFileUploadResponse = await client.files.createSupportFileUpload('<SPACE_ID>', "NAME", '<PARENT_ID>', params);

Creates the support file upload and returns the support file upload URL, allowing you to pass additional request headers.

let params: SupportFileUploadCreateOptionalParams = {
    parentMajorVersion: 1,
    supportFileKey: "KEY",
    multipart: true,
};
let headers = { "If-Match": "<etag-value>" };

let uploadResponse: SupportFileUploadResponse = await client.files.createSupportFileUploadWithOptions(
  "<SPACE_ID>",
  "<NAME>",
  "<PARENT_ID>",
  { params, requestHeaders: headers }
);

Upload File

Uploads a file/support file to the pre-signed upload url.

let options: UploadOptionalParams = {
      chunkSize: 1024 * 1024 * 10,
      maxConcurrentRequests: 5,
  }
let result : boolean = await client.files.uploadFile('<SPACE_ID>','<UPLOAD_ID>', file_content, options)

Listen To events

To monitor the progress of an operation, you can subscribe to various events as shown below:

client.events.subscribe([
  EventType.UPLOAD_FILE_CREATED,
  EventType.UPLOAD_STARTED,
  EventType.UPLOAD_PROGRESS,
  EventType.UPLOAD_COMPLETED,
  EventType.UPLOAD_FAILED,
], (event) => {
  console.log(event);
});

This subscription will log information about the upload process, including when it starts, progresses, completes, or fails.

Get upload details

Retrieve the upload details by Id

let fileUploadResponse : FileUploadResponse = await client.files.getUploadDetails('<SPACE_ID>','<UPLOAD_ID>')

Link support files

Link support files to a specific version of a file.

let params: SupportFileLinkParams = {
    links: {
        "<KEY>": {
            id: "SUPPORT_FILE_ID",
            version: '4.0'
        }
    }
}
let result: FileResponse = await client.files.createOrUpdateLinks('<SPACE_ID>', '<FILE_ID>', <FILE_MAJOR_VERSION>, params)

Link support files to a specific version of a file and return minimal response

let result: MinimalFileResponse = await client.files.createOrUpdateLinks('<SPACE_ID>', '<FILE_ID>', <FILE_MAJOR_VERSION>, params, true)

Lock

Lock a file within a space. Locking a file will prevent other actors from creating a new version or deleting the file. A locked file will be deleted in a recursive parent deletion. Support files cannot be locked.

let params: FileLockOptionalParams = { reason: "Reason to lock a file" }
let result: FileResponse = await client.files.lock('<SPACE_ID>','<FILE_ID>', params)

Lock a file nd return minimal response.

let params: FileLockOptionalParams = { reason: "Reason to lock a file"}
let result: MinimalFileResponse = await client.files.lock('<SPACE_ID>','<FILE_ID>', params, true)

Unlock

Unlock a file within a space. Unlocking a file will allow other actors to create a new version or delete the file. The actor who locked the file or an actor with the ContentManager role attached to the file or parent resource is allowed to unlock the file.

let result: FileResponse = await client.files.unlock('<SPACE_ID>','<FILE_ID>')

Unlock a file and return a minimal response

let result: MinimalFileResponse = await client.files.unlock('<SPACE_ID>','<FILE_ID>', true)

Checkout

Checkout a file within a space. Checking out a file will prevent other actors from creating a new version or performing other mutation operations. A checked out file will be deleted in a recursive parent deletion. Support files cannot be checked out.

let result: FileResponse = await client.files.checkout('<SPACE_ID>','<FILE_ID>')

Checkout a file with a reason

let params: FileCheckoutOptionalParams = { reason: "Working on this file" }
let result: FileResponse = await client.files.checkout('<SPACE_ID>','<FILE_ID>', { params })

Checkout a file and return a minimal response

let result: MinimalFileResponse = await client.files.checkout('<SPACE_ID>','<FILE_ID>', { minimalResponse: true })

Checkout a file with all options including request headers

let params: FileCheckoutOptionalParams = { reason: "Working on this file" }
let requestHeaders = { "If-Match": "1.3" }
let result: FileResponse = await client.files.checkout('<SPACE_ID>','<FILE_ID>', {
    params,
    requestHeaders
})

Checkin

Checkin a file within a space. Checking in a file will allow other actors to create a new version or perform other mutation operations. The actor who checked out the file or an actor with the ContentManager role attached to the file or parent resource is allowed to checkin the file.

let result: FileResponse = await client.files.checkin('<SPACE_ID>','<FILE_ID>')

Checkin a file and return a minimal response

let result: MinimalFileResponse = await client.files.checkin('<SPACE_ID>','<FILE_ID>', true)

Jobs

A job is a background process that is triggered by the user. Async operations will return a job ID which can be used to track the status of the operation.

Get

Get Job details for a given Job ID.

let jobResponse: JobResponse = await client.jobs.get('<JOB_ID>')

Exports

Export is used to zip all children of a folder into a single file. Exports persist for 30 days and capture the state of the folder and its children at the time of creation, with no subsequent changes reflected. It is created in the same cloud provider as the space.

Create

Create an export.

let exportId = await client.exports.create('<SPACE_ID>', '<FOLDER_ID>')

Create an export with includeTopLevel parameter:

// Include top level folder in export (default: true)
let exportId = await client.exports.create('<SPACE_ID>', '<FOLDER_ID>', true)

// Export only children of the folder
let exportId = await client.exports.create('<SPACE_ID>', '<FOLDER_ID>', false)

Get

Get an export by ID.

let export: ExportResponse = await client.exports.get('<SPACE_ID>', '<EXPORT_ID>', '2d')

Resources

The resources entity allows to retrieve files or folders by path or ID, and to fetch multiple resources in a batch.

Get Resource by Path

Get a file or folder by its path:

let resource : FileResponse | FolderResponse = await client.resources.getByPath('<SPACE_ID>', '<PATH>')

Get a file or folder by path with minimal response:

let resource : MinimalFileResponse | MinimalFolderResponse = await client.resources.getByPath('<SPACE_ID>', '<PATH>', true)

Get a file or folder by path with optional parameters:

let params : ResourceGetOptionalParams = { status: "active,deleted" }
let resource : FileResponse | FolderResponse = await client.resources.getByPath('<SPACE_ID>', '<PATH>', params)

Get a file or folder by path with both optional parameters and minimal response:

let params : ResourceGetOptionalParams = { status: "active,deleted" }
let resource : MinimalFileResponse | MinimalFolderResponse = await client.resources.getByPath('<SPACE_ID>', '<PATH>', params, true)

Get Resource by ID

Get a file or folder by its resource ID:

let resource : FileResponse | FolderResponse = await client.resources.get('<SPACE_ID>', '<RESOURCE_ID>')

Get a file or folder by ID with minimal response:

let resource : MinimalFileResponse | MinimalFolderResponse = await client.resources.get('<SPACE_ID>', '<RESOURCE_ID>', true)

Get a file or folder by ID with optional parameters:

let params : ResourceGetOptionalParams = { status: "active,deleted" }
let resource : FileResponse | FolderResponse = await client.resources.get('<SPACE_ID>', '<RESOURCE_ID>', params)

Get a file or folder by ID with both optional parameters and minimal response:

let params : ResourceGetOptionalParams = { status: "active,deleted" }
let resource : MinimalFileResponse | MinimalFolderResponse = await client.resources.get('<SPACE_ID>', '<RESOURCE_ID>', params, true)

Get Resources in Batch

Retrieve multiple resources by IDs or paths in a single call:

let params: ResourceBatchGetParams = { ids: ['<RESOURCE_ID1>', '<RESOURCE_ID2>'] }
let batchResponse : ResourceBatchResponse = await client.resources.getBatch('<SPACE_ID>', params)

Retrieve multiple resources by paths:

let params : ResourceBatchGetParams = { paths: ['<PATH1>', '<PATH2>'] }
let batchResponse : ResourceBatchResponse  = await client.resources.getBatch('<SPACE_ID>', params)

Retrieve multiple resources with minimal response:

let params : ResourceBatchGetParams = { ids: ['<RESOURCE_ID1>', '<RESOURCE_ID2>'] }
let batchResponse : ResourceBatchResponse = await client.resources.getBatch('<SPACE_ID>', params, true)