@inweb/client
Version:
JavaScript REST API client for the Open Cloud Server
655 lines (654 loc) • 27 kB
TypeScript
import { IHttpClient } from "./IHttpClient";
import { Endpoint } from "./Endpoint";
import { ICdaNode, IFileStatus, IFileReferences, IFileVersionInfo, IGrantedTo } from "./IFile";
import { IShortUserDesc } from "./IUser";
import { Model } from "./Model";
import { Permission } from "./Permission";
import { Job } from "./Job";
import { SharedLink } from "./SharedLink";
import { ISharedLinkPermissions } from "./ISharedLink";
/**
* Provides properties and methods for obtaining information about a file on the Open Cloud Server and
* managing its data and versions.
*/
export declare class File extends Endpoint {
private _data;
/**
* @param data - Raw file data received from the server. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
* @param httpClient - HTTP client instance used to send requests to the REST API server.
*/
constructor(data: any, httpClient: IHttpClient);
/**
* Active version number of the file.
*
* @readonly
*/
get activeVersion(): number;
/**
* File creation time (UTC) in the format specified in
* {@link https://www.wikipedia.org/wiki/ISO_8601 | ISO 8601}.
*
* @readonly
*/
get created(): string;
/**
* File custom fields object, to store custom data.
*/
get customFields(): any;
set customFields(value: any);
/**
* Raw file data received from the server. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
*
* @readonly
*/
get data(): any;
set data(value: any);
/**
* Returns a list of file formats in which the active version of the file was exported.
*
* To export file to one of the supported formats create the File Converter job using
* {@link createJob | createJob()}. For an example, see the {@link downloadResource} help.
*
* @readonly
*/
get exports(): string[];
/**
* Geometry data type of the active file version. Can be one of:
*
* - `vsfx` - `VSFX` format, file can be opened in `VisualizeJS` 3D viewer.
* - `gltf` - `glTF` format, file can be opened in `Three.js` 3D viewer.
*
* Returns an empty string if geometry data has not yet been converted. A files without geometry data
* can be exported to other formats, but cannot be opened in viewer.
*/
get geometryType(): string;
/**
* Unique file ID.
*
* @readonly
*/
get id(): string;
/**
* Returns `true` if the source file of the active file version has been deleted.
*
* A files with deleted source file can be opened in the viewer, but cannot be exported to other
* formats.
*
* @readonly
*/
get isFileDeleted(): boolean;
/**
* File name, including the extension.
*/
get name(): string;
set name(value: string);
/**
* If the file is a version, then returns the ID of the original file. Otherwise, returns the file ID.
*
* @readonly
*/
get originalFileId(): string;
/**
* File owner (the user who uploaded the file to the server).
*
* @readonly
*/
get owner(): IShortUserDesc;
/**
* File preview image URL or empty string if the file does not have a preview. Use
* {@link setPreview | setPreview()} to change preview image.
*
* @readonly
*/
get previewUrl(): string;
/**
* The size of the active version of the file in bytes.
*
* @readonly
*/
get size(): number;
/**
* Total size of all versions of the file in bytes.
*
* @readonly
*/
get sizeTotal(): number;
/**
* File shared link token or `null` if file is not shared yet.
*
* @readonly
*/
get sharedLinkToken(): string;
/**
* Jobs status of the active version of the file. This is an object contains keys corresponding to
* different job types:
*
* - `geometry` - status of geometry extraction job (`VSFX` format).
* - `geometryGltf` - status of geometry extraction job (`glTF` format).
* - `properties` - status of property extraction job .
* - `validation` - status of validation job .
*
* Export jobs (`dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf`) and custom jobs appear in the
* status object dynamically as jobs are started.
*
* Each status entity is a record with properties:
*
* - `state` - Job state. Can be `none`, `waiting`, `inprogress`, `done`, or `failed`.
* - `jobId` - Unique ID of the job.
*
* @readonly
*/
get status(): IFileStatus;
/**
* File type, matches the file extension (includes dot).
*
* @readonly
*/
get type(): string;
/**
* File last update time (UTC) in the format specified in
* {@link https://www.wikipedia.org/wiki/ISO_8601 | ISO 8601}.
*
* @readonly
*/
get updatedAt(): string;
/**
* Information about the user who made the last update.
*
* @readonly
*/
get updatedBy(): IShortUserDesc;
/**
* Zero-based file version number for version files. The original file has version `0`.
*/
get version(): number;
/**
* List of the file versions.
*
* @readonly
*/
get versions(): IFileVersionInfo[];
/**
* Reloads file data from the server.
*/
checkout(): Promise<this>;
/**
* Updates file data on the server.
*
* You cannot update other users' files unless they have explicitly granted you `write` access or you
* are an administrator.
*
* @param data - Raw file data. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
*/
update(data: any): Promise<this>;
/**
* Deletes a file and all its versions from the server.
*
* You cannot delete other users' files unless you are an administrator.
*
* You cannot delete a version file, only the original file. To delete a version file use
* {@link deleteVersion | deleteVersion()}.
*
* @returns Returns the raw data of a deleted file. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
*/
delete(): Promise<any>;
/**
* Saves file properties changes to the server. Call this method to update file data on the server
* after any property changes.
*/
save(): Promise<this>;
/**
* Sets or removes the file preview.
*
* @param image - Preview image. Can be a
* {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL} string,
* {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
* {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob} or
* {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object. Setting the `image`
* to `null` will remove the preview.
*/
setPreview(image?: BodyInit | null): Promise<this>;
/**
* Removes the file preview.
*/
deletePreview(): Promise<this>;
/**
* Returns a list of models of the active version of the file.
*/
getModels(): Promise<Model[]>;
getModelTransformMatrix(handle: string): any;
setModelTransformMatrix(handle: string, transform?: any): Promise<this>;
/**
* Object properties.
*
* @typedef {any} Properties
* @property {string} handle - Object original handle.
* @property {string | any} * - Object property. Can be `any` for nested group properties.
*/
/**
* Returns the properties for objects in the active version of the file.
*
* @param handles - Object original handle or handles array. Specify `undefined` to get properties for
* all objects in the file.
* @param group - If the `group` parameter is `true`, properties are returned grouped by category. By
* default, or if `group` is set to `false`, properties are returned ungrouped.
*
* To get grouped properties, the `--properties_group` command line argument must be specified for the
* `properties` File Converter job when {@link Client.uploadFile | uploading the file}:
*
* ```javascript
* await client.uploadFile(file, {
* geometry: true,
* properties: true,
* jobParameters: { properties: "--properties_group" },
* waitForDone: true,
* });
* ```
*
* or when creating the {@link extractProperties | extract file properties} job:
*
* ```javascript
* await file.extractProperties("--properties_group");
* ```
*
* Otherwise, the properties will be returned ungrouped, even if the `group` is `true`.
*/
getProperties(handles?: string | string[], group?: boolean): Promise<any[]>;
/**
* Search pattern.
*
* @typedef {any} SearchPattern
* @property {string} key - Property name.
* @property {string} value - Property value.
*/
/**
* Query operator. Operator name can be `$and`, `$or`, `$not`, `$eq`, `$regex`.
*
* @typedef {any} QueryOperator
* @property {string | SearchPattern[] | QueryOperator[]} * - Array of the query values or patterns for
* operator.
*/
/**
* Returns the list of original handles for objects in the active version of the file that match the
* specified patterns. Search patterns may be combined using query operators.
*
* @example Simple search pattern.
*
* ```javascript
* searchPattern = {
* key: "Category",
* value: "OST_Stairs",
* };
* ```
*
* @example Search patterns combination.
*
* ```javascript
* searchPattern = {
* $or: [
* {
* $and: [
* { key: "Category", value: "OST_GenericModel" },
* { key: "Level", value: "03 - Floor" },
* ],
* },
* { key: "Category", value: "OST_Stairs" },
* ],
* };
* ```
*
* @param {SearchPattern | QueryOperator} searchPattern - Search pattern or combination of the
* patterns, see example below.
* @returns {Promise<Properties[]>}
*/
searchProperties(searchPattern: any): Promise<any[]>;
/**
* Returns the CDA tree for an active version of the file.
*/
getCdaTree(): Promise<ICdaNode[]>;
/**
* Returns a list of file viewpoints. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
*/
getViewpoints(): Promise<any[]>;
/**
* Saves a new file viewpoint to the server. To create a viewpoint use `Viewer.createViewpoint()`.
*
* @param viewpoint - Viewpoint object. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
*/
saveViewpoint(viewpoint: any): Promise<any>;
/**
* Deletes the specified file viewpoint.
*
* @param guid - Viewpoint GUID.
* @returns Returns the raw data of a deleted viewpoint. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
*/
deleteViewpoint(guid: string): Promise<any>;
/**
* Returns viewpoint snapshot as base64-encoded
* {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
*
* @param guid - Viewpoint GUID.
*/
getSnapshot(guid: string): Promise<string>;
/**
* Returns viewpoint snapshot data.
*
* @param guid - Viewpoint GUID.
* @param bitmapGuid - Bitmap GUID.
*/
getSnapshotData(guid: string, bitmapGuid: string): Promise<string>;
/**
* Downloads the active version of the file from the server.
*
* You cannot download other users' files unless they have explicitly granted you `readSourceFile`
* access or you are an administrator.
*
* @param onProgress - Download progress callback.
* @param signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows
* to communicate with a fetch request and abort it if desired.
*/
download(onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
/**
* Downloads a resource file of the active version of the file. Resource files are files that contain
* model scene descriptions, or geometry data, or exported files.
*
* You cannot download resources of other users' files unless they have explicitly granted you `read`
* access or you are an administrator.
*
* @example Export file to PDF.
*
* ```javascript
* const job = await file.createJob("pdf");
* await job.waitForDone();
* const pdfResourceName = file.exports.find((x) => x.endsWith(".pdf"));
* const arrayBuffer = await file.downloadResource(pdfResourceName);
* const fileName = file.name + ".pdf";
* FileSaver.saveAs(new Blob([arrayBuffer]), fileName);
* ```
*
* @param dataId - Resource file name.
* @param onProgress - Download progress callback.
* @param signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows
* to communicate with a fetch request and abort it if desired.
*/
downloadResource(dataId: string, onProgress?: (progress: number, chunk: Uint8Array) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
/**
* Downloads a part of resource file of the active version of the file. Resource files are files that
* contain model scene descriptions, or geometry data, or exported files.
*
* @param dataId - Resource file name.
* @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
* the server request. If specified, server-side caching may not work.
* @param ranges - Ranges of resource file contents to download. See
* {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
* more details.
* @param onProgress - Download progress callback.
* @param signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows
* to communicate with a fetch request and abort it if desired.
*/
downloadResourceRange(dataId: string, requestId: number | string, ranges: Array<{
begin: number;
end: number;
requestId: number;
}>, onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
/**
* Returns a list of file references.
*
* References are images, fonts, external models or any other files to correct rendering of the file.
*
* @param signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal, which
* can be used to abort waiting as desired.
*/
getReferences(signal?: AbortSignal): Promise<IFileReferences>;
/**
* Sets the file references.
*
* References are images, fonts, external models or any other files to correct rendering of the file.
*
* Reference files must be uploaded to the server before they can be assigned to the current file.
* Setting reference files must be done before extracting geometry and properties of the main file.
*
* @param references - File references.
*/
setReferences(references: IFileReferences): Promise<IFileReferences>;
/**
* Creates a new job on the server for the active version of the file.
*
* You cannot create jobs for other users' files unless they have explicitly granted you `createJob`
* access or you are an administrator.
*
* @param outputFormat - The job type. Can be one of:
*
* - `geometry` - Convert file geometry data to `VSFX` format for opening in `VisualizeJS` 3D viewer.
* - `geometryGltf` - Convert file geometry data to `glTF` format for opening in `Three.js` 3D viewer.
* - `properties` - Extract file properties.
* - `validation` - Validate the IFC file.
* - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format. Use
* {@link exports} to get the list of completed file exports. Use
* {@link downloadResource | downloadResource()} to download the exported file.
* - Other custom job name. Custom job must be registered in the job templates.
*
* @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
* object or command line arguments in form `--arg=value`.
*/
createJob(outputFormat: string, parameters?: string | object): Promise<Job>;
/**
* Creates a File Converter job to convert geometry data of active version of the file to the specified
* format. This is alias to {@link createJob | createJob("geometry")}.
*
* @param type - Geometry data type. Can be one of:
*
* - `vsfx` - `VSFX` format (default), for opening a file in `VisualizeJS` 3D viewer.
* - `gltf` - `glTF` format, for opening a file in `Three.js` 3D viewer.
*
* @param parameters - Parameters for the File Converter job. Can be given as command line arguments in
* form `--arg=value`.
*/
extractGeometry(type?: string, parameters?: string | object): Promise<Job>;
/**
* Creates a File Converter job to extract properties of the active version of the file. This is alias
* to {@link createJob | createJob("properties")}.
*
* @param parameters - Parameters for the File Converter job. Can be given as command line arguments in
* form `--arg=value`.
*/
extractProperties(parameters?: string | object): Promise<Job>;
/**
* Creates an IFC validator job to validate the active version of the file. This is alias to
* {@link createJob | createJob("validation")}.
*
* To get validation report use {@link downloadResource | downloadResource("validation_report.json")}.
*
* @param parameters - Parameters for the IFC validator tool. Can be given as command line arguments in
* form `--arg=value`.
*/
validate(parameters?: string | object): Promise<Job>;
/**
* Waits for jobs of the active version of the file to be done. Job is done when it changes to `none`,
* `done` or `failed` status.
*
* @param jobs - Job name or array of job names to wait on. Can be `geometry`, `geometryGltf`,
* `properties`, `validation`, `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` or custom job
* name.
* @param waitAll - If this parameter is `true`, the function returns when all the specified jobs have
* done. If `false`, the function returns when any one of the jobs are done.
* @param params - An object containing waiting parameters.
* @param params.timeout - The time, in milliseconds that the function should wait jobs. If no one jobs
* are done during this time, the `TimeoutError` exception will be thrown.
* @param params.interval - The time, in milliseconds, the function should delay in between checking
* jobs status.
* @param params.signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal, which
* can be used to abort waiting as desired. If waiting has been aborted, the `AbortError` exception
* will be thrown.
* @param params.onCheckout - Waiting progress callback. Return `true` to cancel waiting.
*/
waitForDone(jobs: string | string[], waitAll?: boolean, params?: {
timeout?: number;
interval?: number;
signal?: AbortSignal;
onCheckout?: (file: File, ready: boolean) => boolean;
}): Promise<this>;
/**
* Returns a list of file permissions.
*/
getPermissions(): Promise<Permission[]>;
/**
* Returns information about specified file permission.
*
* @param permissionId - Permission ID.
*/
getPermission(permissionId: string): Promise<Permission>;
/**
* Grants specified file permissions to user, project, group, or all users.
*
* @example Grant the specified user permission to "read" the file.
*
* ```javascript
* const action = "read";
* const grantedTo = { user: { id: myUser.id, email: myUser.email } };
* await file.createPermission(action, grantedTo);
* ```
*
* @example Add a file to the specified project in "read-only" mode.
*
* ```javascript
* const actions = ["read", "readSourceFile"];
* const grantedTo = { project: { id: myProject.id, name: myProject.name } };
* await file.createPermission(actions, grantedTo);
* ```
*
* @param actions - A single action or list of actions allowed for this permission:
*
* - `read` - The ability to read file description, geometry data and properties.
* - `readSourceFile` - The ability to download source file.
* - `write` - The ability to modify file name, description and references.
* - `readViewpoint` - The ability to read file viewpoints.
* - `createViewpoint` - The ability to create new file viewpoints.
* - `deleteViewpoint` - The ability to delete existing file viewpoints.
*
* @param grantedTo - A user, project, or group that will get access to the file.
* @param _public - Specifies whether all users have access to the file or not.
*/
createPermission(actions: string | string[], grantedTo: IGrantedTo | IGrantedTo[], _public?: boolean): Promise<Permission>;
/**
* Revokes specified file permission.
*
* @param permissionId - Permission ID.
* @returns Returns the raw data of a deleted permission. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud File Permissions API}.
*/
deletePermission(permissionId: string): Promise<any>;
/**
* Uploads the new version of the file to the server, convert the geometry data and extract properties
* as needed.
*
* @param file - {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object are
* generally retrieved from a {@link https://developer.mozilla.org/docs/Web/API/FileList | FileList}
* object returned as a result of a user selecting files using the HTML `<input>` element.
* @param params - An object containing upload parameters.
* @param params.geometry - Create job to convert file geometry data. The geometry data type is the
* same as the original file.
* @param params.properties - Create job to extract file properties.
* @param params.waitForDone - Wait for geometry and properties jobs to complete.
* @param params.timeout - The time, in milliseconds that the function should wait jobs. If no one jobs
* are done during this time, the `TimeoutError` exception will be thrown.
* @param params.interval - The time, in milliseconds, the function should delay in between checking
* jobs status.
* @param params.signal - An
* {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal, which
* can be used to abort waiting as desired.
* @param params.onProgress - Upload progress callback.
*/
uploadVersion(file: globalThis.File, params?: {
geometry?: boolean;
properties?: boolean;
waitForDone?: boolean;
timeout?: number;
interval?: number;
signal?: AbortSignal;
onProgress?: (progress: number, file: globalThis.File) => void;
}): Promise<File>;
/**
* Returns a list of version files.
*/
getVersions(): Promise<File[]>;
/**
* Returns information about the specified version file.
*
* @param version - Desired version.
*/
getVersion(version: number): Promise<File>;
/**
* Deletes the specified file version.
*
* @param version - Version to delete.
* @returns Returns the raw data of a deleted version file. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
*/
deleteVersion(version: number): Promise<any>;
/**
* Replaces the active version of the file with the selected version.
*
* @param version - Desired active version.
*/
setActiveVersion(version: number): Promise<this>;
/**
* Makes the given version active on client side. Does not change the active file version on the
* server.
*
* This version change will affect the result:
*
* - {@link getModels | getModels()}
* - {@link getProperties | getProperties()}
* - {@link searchProperties | searchProperties()}
* - {@link getCdaTree | getCdaTree()}
* - {@link download | download()}
* - {@link downloadResource | downloadResource()}
* - {@link createJob | createJob()}
* - {@link extractGeometry | extractGeometry()}
* - {@link extractProperties | extractProperties()}
* - {@link validate | validate()}
* - {@link waitForDone | waitForDone()}
* - Viewer.open()
*
* Other clients will still continue to use the current active version of the file. Use `undefined` to
* revert back to the active version.
*
* You need to reload the file data using {@link checkout | checkout()} to match the size and status
* fields to the version you selected.
*/
useVersion(version?: number): this;
/**
* Deletes the source file of the active file version from the server.
*/
deleteSource(): Promise<this>;
/**
* Creates a file shared link.
*
* @param permissions - Share permissions.
*/
createSharedLink(permissions?: ISharedLinkPermissions): Promise<SharedLink>;
/**
* Returns information about the file shared link or `undefined` if file is not shared yet.
*/
getSharedLink(): Promise<SharedLink>;
/**
* Deletes the file shared link.
*
* @returns Returns the raw data of a deleted shared link. For more information, see
* {@link https://cloud.opendesign.com/docs//pages/server/api.html#ShareLinks | Open Cloud SharedLinks API}.
*/
deleteSharedLink(): Promise<any>;
}