@inweb/client
Version:
JavaScript REST API client for the Open Cloud Server
624 lines (623 loc) • 25.3 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 File Converter job using
* {@link createJob | createJob()}. To download exported file use
* {@link downloadResource | downloadResource()}.
*
* For an example of exporting files to other formats, 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` viewer.
* - `gltf` - `glTF` format, file can be opened in `Three.js` viewer.
*
* Returns an empty string if geometry data has not yet been converted. A files without geometry data
* can be exported to other formas, 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 information.
*
* @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;
/**
* Data status of the active version of the file. Contains:
*
* - `geometry` - status of geometry data of `vsfx` type.
* - `geometryGltf` - status of geometry data of `gltf` type.
* - `properties` - status of properties.
* - `validation` - status of validation.
*
* Each status entity is a record with properties:
*
* - `state` - Data state. Can be `none`, `waiting`, `inprogress`, `done` or `failed`.
* - `jobId` - Unique ID of the data job.
*
* @readonly
*/
get status(): IFileStatus;
/**
* File type, matches the file extension.
*
* @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.
*
* @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 a version file using `delete()`, 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 properties.
*/
/**
* Returns the properties for an 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.
*/
getProperties(handles?: string | string[]): 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 an 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 {SeacrhPattern | 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 source file of active version of the file from the server.
*
* @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.
*
* @example Export file to DWG.
*
* ```javascript
* const job = await file.crateJob("dwg");
* await job.waitForDone();
* const dwgFileName = file.exports.find((x) => x.endsWith(".dwg"));
* const arrayBuffer = await file.downloadResource(dwgFileName);
* const blob = new Blob([arrayBuffer]);
* const fileName = file.name + ".dwg";
* FileSaver.saveAs(blob, 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 ranges - A range of resource file contents to download.
* @param requestId - Request ID for download progress callback.
* @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, ranges: Array<{
begin: number;
end: number;
requestId: number;
}>, onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
/**
* Deprecated since `25.3`. Use {@link downloadResource | downloadResource()} instead.
*
* @deprecated
*/
partialDownloadResource(dataId: string, onProgress?: (progress: number, downloaded: Uint8Array) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
/**
* Deprecated since `25.3`. Use {@link downloadResourceRange | downloadResourceRange()} instead.
*
* @deprecated
*/
downloadFileRange(requestId: number, records: any | null, dataId: string, onProgress?: (progress: number, downloaded: Uint8Array, requestId: number) => void, signal?: AbortSignal): Promise<void>;
/**
* Returns a list of file references.
*
* References are images, fonts, 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, 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.
*
* @param references - File references.
*/
setReferences(references: IFileReferences): Promise<IFileReferences>;
/**
* Runs a new job on the server for the active version of the file.
*
* @param outputFormat - The job type. Can be one of:
*
* - `geometry` - Convert file geometry data to `VSFX` format suitable for `VisualizeJS` viewer.
* - `geometryGltf` - Convert file geometry data to `glTF` format suitable for `Three.js` viewer.
* - `properties` - Extract file properties.
* - `validation` - Validate the file. Only for `IFC` files.
* - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the one of the supported format.
* Use {@link exports | exports()} to get the list of completed file exports. Use
* {@link downloadResource | downloadResource()} to download the exported file.
* - Other custom job name. Custom job runner must be registered in the job templates before creating a
* job.
*
* @param parameters - Parameters for the job runner. Can be given as command line arguments for the
* File Converter tool in form `--arg=value`.
*/
createJob(outputFormat: string, parameters?: string | object): Promise<Job>;
/**
* Runs a job to convert geometry data of active version of the file. 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` viewer.
* - `gltf` - `glTF` format, for opening a file in `Three.js` viewer.
*
* @param parameters - Parameters for the job runner. Can be given as command line arguments for the
* File Converter tool in form `--arg=value`.
*/
extractGeometry(type?: string, parameters?: string | object): Promise<Job>;
/**
* Runs a job to extract properties of the active version of the file. This is alias to
* {@link createJob | createJob("properties")}.
*
* @param parameters - Parameters for the job runner. Can be given as command line arguments for the
* File Converter tool in form `--arg=value`.
*/
extractProperties(parameters?: string | object): Promise<Job>;
/**
* Runs a 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 job runner. Can be given as command line arguments for the
* File Converter tool 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 or job array 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.
* @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>;
/**
* Creates a new file permission for a user, project, or group.
*
* @example Grant the specified user permission to "update" the file.
*
* ```javascript
* const action = "update";
* 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 - Actions are allowed to be performed on a file with 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 file viewpoints.
*
* @param grantedTo - A list of entities 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[], _public: boolean): Promise<Permission>;
/**
* Removes the specified permission from the file.
*
* @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 version file.
*
* @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.
*/
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>;
}