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

package/src/resources/ShapeDiverOutputApi.ts

@@ -0,0 +1,64 @@
+import {
+    ShapeDiverRequestCache,
+    ShapeDiverRequestCustomization,
+    ShapeDiverRequestOutputDefinition,
+    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 ShapeDiverOutputApi extends BaseResourceApi {
+
+    constructor (api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * Request a specific version of an output.
+     *
+     * @param sessionId
+     * @param body
+     */
+    async customize (sessionId: string, body: ShapeDiverRequestCustomization): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.put<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/output", body))[1],
+        )
+    }
+
+    /**
+     * Check if a specific version of a requested output has been computed yet.
+     *
+     * @param sessionId
+     * @param body
+     */
+    async getCache (sessionId: string, body: ShapeDiverRequestCache): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.put<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/output/cache", body))[1],
+        )
+    }
+
+    /**
+     * Updates the definitions of the given outputs.
+     *
+     * @param modelId
+     * @param body
+     */
+    async updateDefinitions (modelId: string, body: ShapeDiverRequestOutputDefinition): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.patch<ShapeDiverResponseDto>(this.buildModelUri(modelId) + "/output", body))[1],
+        )
+    }
+
+    /**
+     * List all cached versions of the specified output.
+     *
+     * @param sessionId
+     * @param outputId
+     */
+    async listVersions (sessionId: string, outputId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/output/" + outputId + "/list"))[1],
+        )
+    }
+
+}

package/src/resources/ShapeDiverSdtfApi.ts

@@ -0,0 +1,61 @@
+import { ShapeDiverRequestSdtfUpload, ShapeDiverResponseDto } from "@shapediver/api.geometry-api-dto-v2"
+import { BaseResourceApi, ShapeDiverSdkApi, ShapeDiverSdkApiResponseType } from "@shapediver/sdk.geometry-api-sdk-core"
+import { sendRequest } from "../utils/utils"
+
+export class ShapeDiverSdtfApi extends BaseResourceApi {
+
+    constructor (api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * List all sdTF-assets of the given namespace.
+     *
+     * @param sessionId
+     * @param namespace
+     */
+    async list (sessionId: string, namespace: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(`${ this.buildSessionUri(sessionId) }/sdtf/${ namespace }/list`))[1])
+    }
+
+    /**
+     * Download a sdTF-asset.
+     *
+     * @param sessionId
+     * @param sdtfId - Format: "<namespace>/<sdTF id>"
+     */
+    async get (sessionId: string, sdtfId: string): Promise<ArrayBuffer> {
+        return await sendRequest(async () =>
+            (await this.api.get<ArrayBuffer>(
+                `${ this.buildSessionUri(sessionId) }/sdtf/${ sdtfId }`,
+                { responseType: ShapeDiverSdkApiResponseType.DATA },
+            ))[1],
+        )
+    }
+
+    /**
+     * Delete a sdTF-asset.
+     *
+     * @param sessionId
+     * @param sdtfId
+     */
+    async delete (sessionId: string, sdtfId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.delete<ShapeDiverResponseDto>(`${ this.buildSessionUri(sessionId) }/sdtf/${ sdtfId }`))[1],
+        )
+    }
+
+    /**
+     * Request an Upload-URL for a sdTF-asset.
+     *
+     * @param sessionId
+     * @param body
+     */
+    async requestUpload (sessionId: string, body: ShapeDiverRequestSdtfUpload): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/sdtf/upload", body))[1],
+        )
+    }
+
+}

package/src/resources/ShapeDiverSessionApi.ts

@@ -0,0 +1,91 @@
+import {
+    ShapeDiverRequestCustomization,
+    ShapeDiverRequestExport,
+    ShapeDiverRequestTicket,
+    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 ShapeDiverSessionApi extends BaseResourceApi {
+
+    constructor(api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * Create a new ticket that allows to initialize new sessions for the
+     * specified model.
+     *
+     * @param modelId
+     * @param body
+     */
+    async ticket(modelId: string, body: ShapeDiverRequestTicket): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(
+                this.buildModelUri(modelId) + "/ticket",
+                body,
+            ))[1],
+        )
+    }
+
+    /**
+     * Create a new session for a ShapeDiver Model via a ticket.
+     *
+     * @param ticket
+     * @param request - Optional customization or export request.
+     */
+    async init(
+        ticket: string,
+        request?: ShapeDiverRequestCustomization | ShapeDiverRequestExport,
+    ): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(this.buildTicketUri(ticket), request))[1],
+        )
+    }
+
+    /**
+     * Create a new session for a ShapeDiver Model.
+     *
+     * @param ticket
+     * @param request - Optional customization or export request.
+     */
+    async initForModel(
+        modelId: string,
+        request?: ShapeDiverRequestCustomization | ShapeDiverRequestExport,
+    ): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(
+                this.buildModelUri(modelId) + "/session",
+                request,
+            ))[1],
+        )
+    }
+
+    /**
+     * Get the full description of a ShapeDiver Model.
+     *
+     * @param sessionId
+     */
+    async default(sessionId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(
+                this.buildSessionUri(sessionId) + "/default",
+            ))[1],
+        )
+    }
+
+    /**
+     * Close the specified session.
+     *
+     * @param sessionId
+     */
+    async close(sessionId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(
+                this.buildSessionUri(sessionId) + "/close",
+            ))[1],
+        )
+    }
+
+}

package/src/resources/ShapeDiverSystemApi.ts

@@ -0,0 +1,80 @@
+import {
+    ShapeDiverRequestAuthorizationGroup,
+    ShapeDiverRequestLogMessage,
+    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 ShapeDiverSystemApi extends BaseResourceApi {
+
+    constructor (api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * Log the specified message.
+     *
+     * @param sessionId
+     * @param body
+     */
+    async log (sessionId: string, body: ShapeDiverRequestLogMessage): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/log/message", body))[1],
+        )
+    }
+
+    /**
+     * Remove a model with all it's components.
+     *
+     * **WARNING: This operation cannot be undone!**
+     *
+     * @param modelId
+     */
+    async pruneModel (modelId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.delete<ShapeDiverResponseDto>(`${ this.buildSystemUri() }/model/${ modelId }`))[1],
+        )
+    }
+
+    /**
+     * Decrypt the given ticket.
+     *
+     * @param ticket
+     */
+    async decryptTicket (ticket: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(this.buildTicketUri(ticket)))[1],
+        )
+    }
+
+    /**
+     * Create a new authentication group.
+     *
+     * @param body
+     */
+    async authGroup (body: ShapeDiverRequestAuthorizationGroup): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.post<ShapeDiverResponseDto>(this.buildAuthGroupUri(), body))[1],
+        )
+    }
+
+    /**
+     * Returns system information about the Geometry Minions.
+     */
+    async getMinionInfo (): Promise<ShapeDiverResponseDto> {
+        return sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(`${ this.buildSystemUri() }/minions/info`))[1],
+        )
+    }
+
+    /**
+     * Returns system information about the Geometry Workers.
+     */
+    async getWorkerInfo (): Promise<ShapeDiverResponseDto> {
+        return sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(`${ this.buildSystemUri() }/workers/info`))[1],
+        )
+    }
+
+}

package/src/resources/ShapeDiverTextureApi.ts

@@ -0,0 +1,22 @@
+import { 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 ShapeDiverTextureApi extends BaseResourceApi {
+
+    constructor (api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * List all textures of the specified model.
+     *
+     * @param sessionId
+     */
+    async listModelTextures (sessionId: string): Promise<ShapeDiverResponseDto> {
+        return await sendRequest(async () =>
+            (await this.api.get<ShapeDiverResponseDto>(this.buildSessionUri(sessionId) + "/texture/list"))[1],
+        )
+    }
+
+}

package/src/resources/ShapeDiverUtilsApi.ts

@@ -0,0 +1,255 @@
+import {
+    ShapeDiverRequestCache,
+    ShapeDiverRequestCustomization,
+    ShapeDiverRequestExport,
+    ShapeDiverResponseDto,
+    ShapeDiverResponseExport,
+    ShapeDiverResponseOutput,
+} from "@shapediver/api.geometry-api-dto-v2"
+import {
+    BaseResourceApi,
+    ShapeDiverError,
+    ShapeDiverSdkApi,
+    ShapeDiverSdkApiResponseType,
+} from "@shapediver/sdk.geometry-api-sdk-core"
+import { ShapeDiverSdk } from "../ShapeDiverSdk"
+import { sendRequest, sleep } from "../utils/utils"
+
+// TypeScript wrapper for a response type that depend on an input type
+type ShapeDiverSdkUtilsDownloadType<T extends ShapeDiverSdkApiResponseType> =
+    T extends ShapeDiverSdkApiResponseType.TEXT ? string :
+    T extends ShapeDiverSdkApiResponseType.JSON ? Record<string, any> :
+    T extends ShapeDiverSdkApiResponseType.DATA ? ArrayBuffer :
+    never;
+
+export class ShapeDiverUtilsApi extends BaseResourceApi {
+
+    constructor(api: ShapeDiverSdkApi) {
+        super(api)
+    }
+
+    /**
+     * Upload the given file to the specified URL.
+     *
+     * @param url - The target URL of the upload request.
+     * @param data - The data that should be uploaded.
+     * @param contentType - Indicate the original media type of the resource.
+     * @param filename - The name of the file to be uploaded. When a filename has been specified in
+     * the request-upload call, then the same filename has to be specified for the upload as well.
+     */
+    async upload(
+        url: string,
+        data: ArrayBuffer | Record<string, any> | string,
+        contentType: string,
+        filename?: string,
+    ): Promise<any> {
+        return await sendRequest(async () => this.api.put<any>(url, data, {
+            contentType: contentType,
+            contentDisposition: (filename) ? `attachment; filename="${filename}"` : undefined,
+            responseType: ShapeDiverSdkApiResponseType.JSON,
+            disableAuthorization: true,
+            disableCustomHeaders: true,
+        }))
+    }
+
+    /**
+     * Download from the given URL.
+     *
+     * @param url - The target URL of the download request.
+     * @param responseType - Indicates the type of data that the server should respond with if possible.
+     * @returns Array of size 2: [0] = response headers, [1] = response data
+     */
+    async download<T extends ShapeDiverSdkApiResponseType>(url: string, responseType: T): Promise<[
+        Record<string, any>,
+        ShapeDiverSdkUtilsDownloadType<T>,
+    ]> {
+        return await sendRequest(async () => this.api.get<any>(url, {
+            contentType: "application/json",
+            responseType: responseType,
+            disableAuthorization: true,
+            disableCustomHeaders: true,
+        }))
+    }
+
+    /**
+     * Submit a customization request and wait for the result to be finished.
+     *
+     * @param sdk
+     * @param sessionId
+     * @param body
+     * @param maxWaitMsec - Maximum duration to wait for result (in milliseconds), pass value < 0 to disable limit.
+     * @throws {@link ShapeDiverError} in case a maximum duration has been specified and is exceeded.
+     * @returns
+     */
+    async submitAndWaitForCustomization(
+        sdk: ShapeDiverSdk,
+        sessionId: string,
+        body: ShapeDiverRequestCustomization,
+        maxWaitMsec = -1,
+    ): Promise<ShapeDiverResponseDto> {
+        const startMsec = Date.now()
+        const dto = await sendRequest(async () => sdk.output.customize(sessionId, body))
+        const waitMsec = Date.now() - startMsec
+
+        // Reduce the total max waiting time by the amount the customization-request took
+        maxWaitMsec = (maxWaitMsec < 0) ? maxWaitMsec : Math.max(0, maxWaitMsec - waitMsec)
+
+        return ShapeDiverUtilsApi.waitForCustomizationResult(sdk, sessionId, dto, maxWaitMsec)
+    }
+
+    /**
+     * Submit an export request and wait for the result to be finished.
+     *
+     * @param sdk
+     * @param sessionId
+     * @param body
+     * @param maxWaitMsec - Maximum duration to wait for result (in milliseconds), pass value < 0 to disable limit.
+     * @throws {@link ShapeDiverError} in case a maximum duration has been specified and is exceeded.
+     * @returns
+     */
+    async submitAndWaitForExport(
+        sdk: ShapeDiverSdk,
+        sessionId: string,
+        body: ShapeDiverRequestExport,
+        maxWaitMsec = -1,
+    ): Promise<ShapeDiverResponseDto> {
+        const startMsec = Date.now()
+        const dto = await sendRequest(async () => sdk.export.compute(sessionId, body))
+        const waitMsec = Date.now() - startMsec
+
+        // Reduce the total max waiting time by the amount the compute-request took
+        maxWaitMsec = (maxWaitMsec < 0) ? maxWaitMsec : Math.max(0, maxWaitMsec - waitMsec)
+
+        return ShapeDiverUtilsApi.waitForExportResult(sdk, sessionId, body, dto, maxWaitMsec)
+    }
+
+    /**
+     * Given a DTO resulting from a customization request, wait for the results to be finished.
+     *
+     * @param sdk
+     * @param sessionId
+     * @param dto
+     * @param maxWaitMsec - Maximum duration to wait for result (in milliseconds), pass value < 0 to disable limit.
+     * @returns
+     */
+    private static async waitForCustomizationResult(
+        sdk: ShapeDiverSdk,
+        sessionId: string,
+        dto: ShapeDiverResponseDto,
+        maxWaitMsec = -1,
+    ): Promise<ShapeDiverResponseDto> {
+        if (!dto.outputs) return dto
+
+        // Build new cache request
+        const outputVersions: ShapeDiverRequestCache = {}
+        Object
+            .keys(dto.outputs)
+            .forEach(id => outputVersions[id] = (dto.outputs![id] as ShapeDiverResponseOutput).version)
+
+        let delay = ShapeDiverUtilsApi.getMaxOutputDelay(dto)
+        const startMsec = Date.now()
+
+        while (delay > 0) {
+            // Check whether maxWaitMsec has been reached
+            if (maxWaitMsec >= 0) {
+                const waitMsec = Date.now() - startMsec
+                if (waitMsec >= maxWaitMsec) {
+                    throw new ShapeDiverError(`Maximum wait time of ${maxWaitMsec} ms reached`)
+                }
+                if (waitMsec + delay > maxWaitMsec) {
+                    delay = maxWaitMsec - waitMsec
+                }
+            }
+
+            await sleep(delay)
+
+            // Send cache request
+            dto = await sendRequest(async () => sdk.output.getCache(sessionId, outputVersions))
+            delay = ShapeDiverUtilsApi.getMaxOutputDelay(dto)
+        }
+
+        return dto
+    }
+
+    /**
+     * Given a DTO resulting from an export request, wait for the result to be finished.
+     *
+     * @param sdk
+     * @param sessionId
+     * @param dto
+     * @param exportIds
+     * @param outputIds
+     * @param maxWaitMsec - Maximum duration to wait for result (in milliseconds), pass value < 0 to disable limit.
+     * @returns
+     */
+    private static async waitForExportResult(
+        sdk: ShapeDiverSdk,
+        sessionId: string,
+        body: ShapeDiverRequestExport,
+        dto: ShapeDiverResponseDto,
+        maxWaitMsec = -1,
+    ): Promise<ShapeDiverResponseDto> {
+        let delay = ShapeDiverUtilsApi.getMaxExportDelay(dto, body)
+        const startMsec = Date.now()
+
+        while (delay > 0) {
+            // Check whether maxWaitMsec has been reached
+            if (maxWaitMsec >= 0) {
+                const waitMsec = Date.now() - startMsec
+                if (waitMsec >= maxWaitMsec) {
+                    throw new ShapeDiverError(`Maximum wait time of ${maxWaitMsec} ms reached`)
+                }
+                if (waitMsec + delay > maxWaitMsec) {
+                    delay = maxWaitMsec - waitMsec
+                }
+            }
+
+            await sleep(delay)
+
+            // Send cache request
+            dto = await sendRequest(async () => sdk.export.getCache(sessionId, body))
+            delay = ShapeDiverUtilsApi.getMaxExportDelay(dto, body)
+        }
+
+        return dto
+    }
+
+    /**
+     * Get the maximum delay that was reported for output versions.
+     *
+     * @returns maximum delay, -1 in case no delay was reported
+     */
+    private static getMaxOutputDelay(dto: ShapeDiverResponseDto): number {
+        return Math.max(
+            ...Object.values(dto.outputs!)
+                .map(output => output as ShapeDiverResponseOutput)
+                .map(output => output.delay ?? -1),
+        )
+    }
+
+    /**
+     * Get the maximum delay that was reported for the exports. If outputs have been reported as
+     * well, their delay time is included too.
+     *
+     * @returns delay, -1 in case no delay was reported
+     */
+    private static getMaxExportDelay(
+        dto: ShapeDiverResponseDto,
+        body: ShapeDiverRequestExport,
+    ): number {
+        const exports = (Array.isArray(body.exports)) ? body.exports : [body.exports.id]
+        const outputs = body.outputs ?? []
+
+        return Math.max(
+            ...Object.values(dto.exports ?? {})
+                .filter(e => exports.includes(e.id))
+                .map(e => e as ShapeDiverResponseExport)
+                .map(e => e.delay ?? -1),
+            ...Object.values(dto.outputs ?? {})
+                .filter(o => outputs.includes(o.id))
+                .map(o => o as ShapeDiverResponseOutput)
+                .map(o => o.delay ?? -1),
+        )
+    }
+
+}

package/src/utils/utils.ts

@@ -0,0 +1,89 @@
+import {
+    ShapeDiverError,
+    ShapeDiverErrorType,
+    ShapeDiverRequestError as ShapeDiverRequestErrorCore,
+    ShapeDiverResponseError as ShapeDiverResponseErrorCore,
+} from "@shapediver/sdk.geometry-api-sdk-core"
+import { ShapeDiverResponseError } from "../ShapeDiverErrors"
+
+/** Type guard for all error types of the Geometry Backend SDK package. */
+export function isGBError(e: any): e is
+    (ShapeDiverError & ShapeDiverRequestErrorCore & ShapeDiverResponseError) {
+    return e instanceof Error &&
+        "errorType" in e &&
+        Object.values(ShapeDiverErrorType).includes(e.errorType as any)
+}
+
+/** Type guard for a Geometry Backend SDK generic error. */
+export function isGBGenericError(e: any): e is ShapeDiverError {
+    return e instanceof Error &&
+        "errorType" in e &&
+        e.errorType === ShapeDiverErrorType.Generic
+}
+
+/** Type guard for a Geometry Backend SDK request error. */
+export function isGBRequestError(e: any): e is ShapeDiverRequestErrorCore {
+    return e instanceof Error &&
+        "errorType" in e &&
+        e.errorType === ShapeDiverErrorType.Request
+}
+
+/** Type guard for a Geometry Backend SDK response error. */
+export function isGBResponseError(e: any): e is ShapeDiverResponseError {
+    return e instanceof Error &&
+        "errorType" in e &&
+        e.errorType === ShapeDiverErrorType.Response
+}
+
+/**
+ * Sends the given request, handles retries for the HTTP status 429, and maps
+ * the response error object to its typed representation.
+ */
+export async function sendRequest<T>(call: () => Promise<T>): Promise<T> {
+    const retryLimit = 5
+    let retryCounter = 0
+
+    while (retryCounter < retryLimit) {
+        try {
+            return await call()
+        } catch (e) {
+            retryCounter++
+
+            if (e instanceof ShapeDiverResponseErrorCore) {
+                /* Check for special response statuses */
+                if (e.status === 429) {
+                    // 429 Too Many Requests - Extract waiting time from Retry-After header if existing.
+                    const seconds = e.headers["retry-after"] ?? 60  // default is 1 minute
+                    await sleep(Number(seconds) * 1000)
+                    continue
+
+                } else if (e.status === 502) {
+                    await sleep(1000)   // 1 second
+                    continue
+                }
+
+                // Error mapping
+                throw new ShapeDiverResponseError(e)
+            } else {
+                // Not a response error -> something went wrong
+                throw e
+            }
+        }
+    }
+
+    throw new ShapeDiverError("Could not send request: Retry-limit reached")
+}
+
+/** Delays the response for the given number of milliseconds */
+export function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/** Encode the given string to base64 */
+export function encodeBase64(str: string): string {
+    try {
+        return btoa(str)
+    } catch (err) {
+        return Buffer.from(str).toString("base64")
+    }
+}