@shapediver/sdk.geometry-api-sdk-v2 1.8.2 → 1.9.0

package/src/ShapeDiverSdk.ts

@@ -0,0 +1,114 @@
+import {
+  BaseShapeDiverSdk,
+  ShapeDiverSdkConfigType,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { ShapeDiverAnalyticsApi } from "./resources/ShapeDiverAnalyticsApi";
+import { ShapeDiverArSceneApi } from "./resources/ShapeDiverArSceneApi";
+import { ShapeDiverAssetApi } from "./resources/ShapeDiverAssetApi";
+import { ShapeDiverExportApi } from "./resources/ShapeDiverExportApi";
+import { ShapeDiverFileApi } from "./resources/ShapeDiverFileApi";
+import { ShapeDiverGltfApi } from "./resources/ShapeDiverGltfApi";
+import { ShapeDiverModelApi } from "./resources/ShapeDiverModelApi";
+import { ShapeDiverOutputApi } from "./resources/ShapeDiverOutputApi";
+import { ShapeDiverSdtfApi } from "./resources/ShapeDiverSdtfApi";
+import { ShapeDiverSessionApi } from "./resources/ShapeDiverSessionApi";
+import { ShapeDiverSystemApi } from "./resources/ShapeDiverSystemApi";
+import { ShapeDiverTextureApi } from "./resources/ShapeDiverTextureApi";
+import { ShapeDiverUtilsApi } from "./resources/ShapeDiverUtilsApi";
+
+export function create(baseUrl: string, jwt?: string): ShapeDiverSdk {
+  return new ShapeDiverSdk(baseUrl, jwt);
+}
+
+export class ShapeDiverSdk extends BaseShapeDiverSdk {
+  private readonly _analytics: ShapeDiverAnalyticsApi;
+  private readonly _arScene: ShapeDiverArSceneApi;
+  private readonly _asset: ShapeDiverAssetApi;
+  private readonly _export: ShapeDiverExportApi;
+  private readonly _file: ShapeDiverFileApi;
+  private readonly _gltf: ShapeDiverGltfApi;
+  private readonly _model: ShapeDiverModelApi;
+  private readonly _output: ShapeDiverOutputApi;
+  private readonly _sdtf: ShapeDiverSdtfApi;
+  private readonly _session: ShapeDiverSessionApi;
+  private readonly _system: ShapeDiverSystemApi;
+  private readonly _texture: ShapeDiverTextureApi;
+  private readonly _utils: ShapeDiverUtilsApi;
+
+  /**
+   * ShapeDiverSDK constructor
+   *
+   * @param baseUrl - the URL of the target system
+   * @param jwt - the client's jwt
+   */
+  constructor(baseUrl: string, jwt?: string) {
+    super(baseUrl);
+    if (jwt) this.setConfigurationValue(ShapeDiverSdkConfigType.JWT_TOKEN, jwt);
+
+    this._analytics = new ShapeDiverAnalyticsApi(this.sdkApi);
+    this._arScene = new ShapeDiverArSceneApi(this.sdkApi);
+    this._asset = new ShapeDiverAssetApi(this.sdkApi);
+    this._export = new ShapeDiverExportApi(this.sdkApi);
+    this._file = new ShapeDiverFileApi(this.sdkApi);
+    this._gltf = new ShapeDiverGltfApi(this.sdkApi);
+    this._model = new ShapeDiverModelApi(this.sdkApi);
+    this._output = new ShapeDiverOutputApi(this.sdkApi);
+    this._sdtf = new ShapeDiverSdtfApi(this.sdkApi);
+    this._session = new ShapeDiverSessionApi(this.sdkApi);
+    this._system = new ShapeDiverSystemApi(this.sdkApi);
+    this._texture = new ShapeDiverTextureApi(this.sdkApi);
+    this._utils = new ShapeDiverUtilsApi(this.sdkApi);
+  }
+
+  get analytics(): ShapeDiverAnalyticsApi {
+    return this._analytics;
+  }
+
+  get arScene(): ShapeDiverArSceneApi {
+    return this._arScene;
+  }
+
+  get asset(): ShapeDiverAssetApi {
+    return this._asset;
+  }
+
+  get export(): ShapeDiverExportApi {
+    return this._export;
+  }
+
+  get file(): ShapeDiverFileApi {
+    return this._file;
+  }
+
+  get gltf(): ShapeDiverGltfApi {
+    return this._gltf;
+  }
+
+  get model(): ShapeDiverModelApi {
+    return this._model;
+  }
+
+  get output(): ShapeDiverOutputApi {
+    return this._output;
+  }
+
+  get sdtf(): ShapeDiverSdtfApi {
+    return this._sdtf;
+  }
+
+  get session(): ShapeDiverSessionApi {
+    return this._session;
+  }
+
+  get system(): ShapeDiverSystemApi {
+    return this._system;
+  }
+
+  get texture(): ShapeDiverTextureApi {
+    return this._texture;
+  }
+
+  get utils(): ShapeDiverUtilsApi {
+    return this._utils;
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "@shapediver/api.geometry-api-dto-v2";
+export {
+  ShapeDiverError,
+  ShapeDiverRequestError,
+  ShapeDiverSdkApiResponseType,
+  ShapeDiverSdkConfig,
+  ShapeDiverSdkConfigType,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+export { ShapeDiverResponseError } from "./ShapeDiverErrors";
+export { ShapeDiverSdk, create } from "./ShapeDiverSdk";
+export { ShapeDiverResponseFileInfo } from "./resources/ShapeDiverFileApi";
+export {
+  isGBError,
+  isGBGenericError,
+  isGBRequestError,
+  isGBResponseError,
+} from "./utils/utils";

package/src/resources/ShapeDiverAnalyticsApi.ts

@@ -0,0 +1,34 @@
+import {
+  ShapeDiverRequestAnalyticsModel,
+  ShapeDiverResponseDto,
+} from "@shapediver/api.geometry-api-dto-v2";
+import {
+  BaseResourceApi,
+  ShapeDiverSdkApi,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { sendRequest } from "../utils/utils";
+
+export class ShapeDiverAnalyticsApi extends BaseResourceApi {
+  constructor(api: ShapeDiverSdkApi) {
+    super(api);
+  }
+
+  /**
+   * Get model session analytics.
+   *
+   * @param body
+   */
+  async modelSessionStatistics(
+    body: ShapeDiverRequestAnalyticsModel,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.put<ShapeDiverResponseDto>(
+            this.buildAnalyticsUri() + "/session/model",
+            body,
+          )
+        )[1],
+    );
+  }
+}

package/src/resources/ShapeDiverArSceneApi.ts

@@ -0,0 +1,75 @@
+import {
+  BaseResourceApi,
+  ShapeDiverResponseError,
+  ShapeDiverSdkApi,
+  ShapeDiverSdkApiResponseType,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { sendRequest } from "../utils/utils";
+
+export class ShapeDiverArSceneApi extends BaseResourceApi {
+  constructor(api: ShapeDiverSdkApi) {
+    super(api);
+  }
+
+  /**
+   * Checks the existence of the specific AR scene.
+   * @param sceneId
+   * @returns `true` when the AR scene exists, otherwise `false`.
+   */
+  async exists(sceneId: string): Promise<boolean> {
+    return await sendRequest(async () => {
+      try {
+        const [_, status] = await this.api.head(
+          `${this.buildArSceneUri()}/${sceneId}`,
+          { disableAuthorization: true },
+        );
+        return status === 200;
+      } catch (e) {
+        // A 404 HTTP status is returned when the AR scene was not found.
+        if (e instanceof ShapeDiverResponseError && e.status === 404)
+          return false;
+        else throw e;
+      }
+    });
+  }
+
+  /**
+   * Download the glTF file of the specified AR scene.
+   *
+   * @param sceneId - The ID of the AR scene.
+   * @returns Array of size 2: [0] = content data, [1] = content type
+   */
+  async getGltf(sceneId: string): Promise<[ArrayBuffer, string]> {
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(
+        `${this.buildArSceneUri()}/${sceneId}/gltf`,
+        {
+          responseType: ShapeDiverSdkApiResponseType.DATA,
+          disableAuthorization: true,
+        },
+      );
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+
+  /**
+   * Download the USDZ file of the specified AR scene.
+   *
+   * @param sceneId - The ID of the AR scene.
+   * @returns Array of size 2: [0] = content data, [1] = content type
+   */
+  async getUsdz(sceneId: string): Promise<[ArrayBuffer, string]> {
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(
+        `${this.buildArSceneUri()}/${sceneId}/usdz`,
+        {
+          responseType: ShapeDiverSdkApiResponseType.DATA,
+          disableAuthorization: true,
+        },
+      );
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+}

package/src/resources/ShapeDiverAssetApi.ts

@@ -0,0 +1,213 @@
+import {
+  BaseResourceApi,
+  ShapeDiverError,
+  ShapeDiverSdkApi,
+  ShapeDiverSdkApiResponseType,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { encodeBase64, sendRequest } from "../utils/utils";
+
+const apiAssetExportUri = /.+\/session\/.+\/export\/.+/;
+const apiAssetOutputUri = /.+\/session\/.+\/output\/.+/;
+const apiAssetTextureUri = /.+\/session\/.+\/texture\/.+/;
+
+const cdnAssetUri = /.+\/cdn-asset-(exports|outputs|textures)\/.+/;
+const cdnAssetExportUri = /.+\/cdn-asset-exports\/.+/;
+const cdnAssetOutputUri = /.+\/cdn-asset-outputs\/.+/;
+const cdnAssetTextureUri = /.+\/cdn-asset-textures\/.+/;
+
+export class ShapeDiverAssetApi extends BaseResourceApi {
+  constructor(api: ShapeDiverSdkApi) {
+    super(api);
+  }
+
+  /**
+   * Download an export.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getExport(
+    sessionId: string,
+    assetData: string,
+  ): Promise<[ArrayBuffer, string]> {
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(
+        `${this.buildSessionUri(sessionId)}/export/${assetData}`,
+        { responseType: ShapeDiverSdkApiResponseType.DATA },
+      );
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+
+  /**
+   * Download an output.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getOutput(
+    sessionId: string,
+    assetData: string,
+  ): Promise<[ArrayBuffer, string]> {
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(
+        `${this.buildSessionUri(sessionId)}/output/${assetData}`,
+        { responseType: ShapeDiverSdkApiResponseType.DATA },
+      );
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+
+  /**
+   * Downloads the JSON content part of a sdTF output.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getSdtfJsonContent(
+    sessionId: string,
+    assetData: string,
+  ): Promise<Record<string, any>> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ArrayBuffer>(
+            `${this.buildSessionUri(sessionId)}/output/${assetData}`,
+            {
+              responseType: ShapeDiverSdkApiResponseType.JSON,
+              accept: "model/vnd.sdtf+json",
+            },
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Download a texture file.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getTexture(
+    sessionId: string,
+    assetData: string,
+  ): Promise<[ArrayBuffer, string]> {
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(
+        `${this.buildSessionUri(sessionId)}/texture/${assetData}`,
+        { responseType: ShapeDiverSdkApiResponseType.DATA },
+      );
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+
+  /**
+   * Download a glTF file.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getGltf(sessionId: string, assetData: string): Promise<ArrayBuffer> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ArrayBuffer>(
+            `${this.buildSessionUri(sessionId)}/gltf/${assetData}`,
+            { responseType: ShapeDiverSdkApiResponseType.DATA },
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Download a USDZ file.
+   *
+   * @param sessionId
+   * @param assetData
+   */
+  async getUsdz(sessionId: string, assetData: string): Promise<ArrayBuffer> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ArrayBuffer>(
+            `${this.buildSessionUri(sessionId)}/usdz/${assetData}`,
+            { responseType: ShapeDiverSdkApiResponseType.DATA },
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Download an image.
+   *
+   * @param sessionId
+   * @param url - The URL of the image that should be downloaded.
+   * @returns Array of size 2: [0] = content data, [1] = content type.
+   */
+  async downloadImage(
+    sessionId: string,
+    url: string,
+  ): Promise<[ArrayBuffer, string]> {
+    let targetUrl: string;
+
+    if (apiAssetTextureUri.test(url) || cdnAssetTextureUri.test(url)) {
+      // Call ShapeDiver texture-asset URLs directly
+      targetUrl = url;
+    } else {
+      // All other source URLs are called via the download-image endpoint
+      targetUrl = `${this.buildSessionUri(sessionId)}/image?url=${encodeBase64(url)}`;
+    }
+
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(targetUrl, {
+        responseType: ShapeDiverSdkApiResponseType.DATA,
+        disableAuthorization: cdnAssetUri.test(url), // disable for CDN URLs
+      });
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType];
+    });
+  }
+
+  /**
+   * Fetches a ShapeDiver asset of the following types:
+   *  * Output
+   *  * Export
+   *  * Texture
+   *
+   * This function works similar to {@link getOutput}, {@link getExport} and {@link getTexture}, but does not require
+   * extracted _session ID_ and _asset data_ parameters.
+   *
+   * @param url - The URL of the asset that should be fetched.
+   * @returns Array of size 3: [0] = content data, [1] = content type, [2] = asset type.
+   * @throws {@link ShapeDiverError} when the given URL is not a valid ShapeDiver asset URL.
+   */
+  async getAsset(
+    url: string,
+  ): Promise<[ArrayBuffer, string, "output" | "export" | "texture"]> {
+    let type: "output" | "export" | "texture";
+
+    // Check if the given URL is a valid API or CDN asset URL
+    if (apiAssetExportUri.test(url) || cdnAssetExportUri.test(url))
+      type = "export";
+    else if (apiAssetOutputUri.test(url) || cdnAssetOutputUri.test(url))
+      type = "output";
+    else if (apiAssetTextureUri.test(url) || cdnAssetTextureUri.test(url))
+      type = "texture";
+    else
+      throw new ShapeDiverError(
+        "Cannot fetch asset: Invalid URL (only ShapeDiver asset URLs are allowed).",
+      );
+
+    return await sendRequest(async () => {
+      const [header, data] = await this.api.get<ArrayBuffer>(url, {
+        responseType: ShapeDiverSdkApiResponseType.DATA,
+        disableAuthorization: cdnAssetUri.test(url), // disable for CDN URLs
+      });
+      const contentType = header["Content-Type"] ?? header["content-type"];
+      return [data, contentType, type];
+    });
+  }
+}

package/src/resources/ShapeDiverExportApi.ts

@@ -0,0 +1,100 @@
+import {
+  ShapeDiverRequestCache,
+  ShapeDiverRequestExport,
+  ShapeDiverRequestExportDefinition,
+  ShapeDiverResponseDto,
+} from "@shapediver/api.geometry-api-dto-v2";
+import {
+  BaseResourceApi,
+  ShapeDiverSdkApi,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { sendRequest } from "../utils/utils";
+
+export class ShapeDiverExportApi extends BaseResourceApi {
+  constructor(api: ShapeDiverSdkApi) {
+    super(api);
+  }
+
+  /**
+   * Request a specific version of an export.
+   *
+   * @param sessionId
+   * @param body
+   */
+  async compute(
+    sessionId: string,
+    body: ShapeDiverRequestExport,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.put<ShapeDiverResponseDto>(
+            this.buildSessionUri(sessionId) + "/export",
+            body,
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Check if a specific version of a requested export has been computed yet.
+   *
+   * @param sessionId
+   * @param body
+   */
+  async getCache(
+    sessionId: string,
+    body: ShapeDiverRequestCache | ShapeDiverRequestExport,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.put<ShapeDiverResponseDto>(
+            this.buildSessionUri(sessionId) + "/export/cache",
+            body,
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Updates the definitions of the given exports.
+   *
+   * @param modelId
+   * @param body
+   */
+  async updateDefinitions(
+    modelId: string,
+    body: ShapeDiverRequestExportDefinition,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.patch<ShapeDiverResponseDto>(
+            this.buildModelUri(modelId) + "/export",
+            body,
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * List all cached versions of the specified export.
+   *
+   * @param sessionId
+   * @param exportId
+   */
+  async listVersions(
+    sessionId: string,
+    exportId: string,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ShapeDiverResponseDto>(
+            this.buildSessionUri(sessionId) + "/export/" + exportId + "/list",
+          )
+        )[1],
+    );
+  }
+}

package/src/resources/ShapeDiverFileApi.ts

@@ -0,0 +1,151 @@
+import {
+  ShapeDiverRequestFileUpload,
+  ShapeDiverResponseDto,
+} from "@shapediver/api.geometry-api-dto-v2";
+import {
+  BaseResourceApi,
+  ShapeDiverSdkApi,
+  ShapeDiverSdkApiResponseType,
+} from "@shapediver/sdk.geometry-api-sdk-core";
+import { sendRequest } from "../utils/utils";
+
+const contentDisposition = require("content-disposition");
+
+export interface ShapeDiverResponseFileInfo {
+  filename?: string;
+  size?: number;
+}
+
+export class ShapeDiverFileApi extends BaseResourceApi {
+  constructor(api: ShapeDiverSdkApi) {
+    super(api);
+  }
+
+  /**
+   * List all file-assets of the given parameter.
+   *
+   * @param sessionId
+   * @param paramId
+   */
+  async list(
+    sessionId: string,
+    paramId: string,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ShapeDiverResponseDto>(
+            `${this.buildSessionUri(sessionId)}/file/${paramId}/list`,
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Get information about a file-asset of a parameter.
+   *
+   * @param sessionId
+   * @param paramId
+   */
+  async info(
+    sessionId: string,
+    paramId: string,
+    fileId: string,
+  ): Promise<ShapeDiverResponseFileInfo> {
+    return await sendRequest(async () => {
+      const headers = (
+        await this.api.head(
+          `${this.buildSessionUri(sessionId)}/file/${paramId}/${fileId}`,
+        )
+      )[0];
+
+      const res: ShapeDiverResponseFileInfo = {
+        size: Number(
+          headers.get("Content-Length") || headers.get("content-length"),
+        ),
+      };
+
+      // Extract filename from Content-Disposition header if available
+      const contentDispositionHeader =
+        headers.get("Content-Disposition") ||
+        headers.get("content-disposition");
+      if (typeof contentDispositionHeader === "string") {
+        try {
+          res.filename = contentDisposition.parse(
+            contentDispositionHeader,
+          ).parameters.filename;
+        } catch (_) {
+          res.filename = undefined;
+        }
+      }
+
+      return res;
+    });
+  }
+
+  /**
+   * Download a file-asset.
+   *
+   * @param sessionId
+   * @param paramId
+   * @param fileId
+   */
+  async get(
+    sessionId: string,
+    paramId: string,
+    fileId: string,
+  ): Promise<ArrayBuffer> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.get<ArrayBuffer>(
+            `${this.buildSessionUri(sessionId)}/file/${paramId}/${fileId}`,
+            { responseType: ShapeDiverSdkApiResponseType.DATA },
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Delete a file-asset.
+   *
+   * @param sessionId
+   * @param paramId
+   * @param fileId
+   */
+  async delete(
+    sessionId: string,
+    paramId: string,
+    fileId: string,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.delete<ShapeDiverResponseDto>(
+            `${this.buildSessionUri(sessionId)}/file/${paramId}/${fileId}`,
+          )
+        )[1],
+    );
+  }
+
+  /**
+   * Request an Upload-URL for a file.
+   *
+   * @param sessionId
+   * @param body
+   */
+  async requestUpload(
+    sessionId: string,
+    body: ShapeDiverRequestFileUpload,
+  ): Promise<ShapeDiverResponseDto> {
+    return await sendRequest(
+      async () =>
+        (
+          await this.api.post<ShapeDiverResponseDto>(
+            this.buildSessionUri(sessionId) + "/file/upload",
+            body,
+          )
+        )[1],
+    );
+  }
+}