@shapediver/sdk.geometry-api-sdk-v2 2.0.1 → 2.1.0

package/dist/configuration.d.ts

@@ -1,8 +1,14 @@
+import { RawAxiosRequestConfig } from 'axios';
 import { Configuration as ClientConfig, ConfigurationParameters as ClientConfigParams } from './client/configuration';
-export interface ConfigurationParameters extends ClientConfigParams {
+export interface ConfigurationParameters extends Pick<ClientConfigParams, 'accessToken' | 'basePath'> {
+    baseOptions?: RawAxiosRequestConfig;
+    useCustomAxios?: boolean;
+    maxRetries?: number;
 }
 export declare class Configuration extends ClientConfig {
-    protected readonly sdkVersion = "2.0.1";
+    protected readonly sdkVersion = "2.1.0";
+    readonly useCustomAxios: boolean;
+    readonly maxRetries: number;
     constructor(param?: ConfigurationParameters);
 }
 //# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,aAAa,IAAI,YAAY,EAC7B,uBAAuB,IAAI,kBAAkB,EAChD,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;CAAG;AAEtE,qBAAa,aAAc,SAAQ,YAAY;IAC3C,SAAS,CAAC,QAAQ,CAAC,UAAU,WAAW;gBAE5B,KAAK,GAAE,uBAA4B;CAgBlD"}
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EACH,aAAa,IAAI,YAAY,EAC7B,uBAAuB,IAAI,kBAAkB,EAChD,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,uBACb,SAAQ,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,UAAU,CAAC;IAO5D,WAAW,CAAC,EAAE,qBAAqB,CAAC;IASpC,cAAc,CAAC,EAAE,OAAO,CAAC;IASzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAc,SAAQ,YAAY;IAC3C,SAAS,CAAC,QAAQ,CAAC,UAAU,WAAW;IAExC,SAAgB,cAAc,EAAE,OAAO,CAAC;IACxC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,KAAK,GAAE,uBAA4B;CAkBlD"}

package/dist/configuration.js

@@ -4,11 +4,13 @@ exports.Configuration = void 0;
 const configuration_1 = require("./client/configuration");
 class Configuration extends configuration_1.Configuration {
     constructor(param = {}) {
-        var _a, _b;
+        var _a, _b, _c, _d;
         super(param);
-        this.sdkVersion = '2.0.1';
-        this.baseOptions = (_a = this.baseOptions) !== null && _a !== void 0 ? _a : {};
-        this.baseOptions.headers = (_b = this.baseOptions.headers) !== null && _b !== void 0 ? _b : {};
+        this.sdkVersion = '2.1.0';
+        this.useCustomAxios = (_a = param.useCustomAxios) !== null && _a !== void 0 ? _a : true;
+        this.maxRetries = (_b = param.maxRetries) !== null && _b !== void 0 ? _b : 5;
+        this.baseOptions = (_c = this.baseOptions) !== null && _c !== void 0 ? _c : {};
+        this.baseOptions.headers = (_d = this.baseOptions.headers) !== null && _d !== void 0 ? _d : {};
         const userAgent = `sd-sdk/typescript/${this.sdkVersion}`;
         if (typeof process === 'object' && !this.baseOptions.headers['User-Agent']) {
             this.baseOptions.headers['User-Agent'] = userAgent;

package/dist/configuration.js.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":";;;AAAA,0DAGgC;AAIhC,MAAa,aAAc,SAAQ,6BAAY;IAG3C,YAAY,QAAiC,EAAE;;QAC3C,KAAK,CAAC,KAAK,CAAC,CAAC;QAHE,eAAU,GAAG,OAAO,CAAC;QAKpC,IAAI,CAAC,WAAW,GAAG,MAAA,IAAI,CAAC,WAAW,mCAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,WAAW,CAAC,OAAO,GAAG,MAAA,IAAI,CAAC,WAAW,CAAC,OAAO,mCAAI,EAAE,CAAC;QAE1D,MAAM,SAAS,GAAG,qBAAqB,IAAI,CAAC,UAAU,EAAE,CAAC;QAEzD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAEzE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;QACvD,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,CAAC;YAE7D,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAAC;QACnE,CAAC;IACL,CAAC;CACJ;AAnBD,sCAmBC"}
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":";;;AACA,0DAGgC;AA+BhC,MAAa,aAAc,SAAQ,6BAAY;IAM3C,YAAY,QAAiC,EAAE;;QAC3C,KAAK,CAAC,KAAK,CAAC,CAAC;QANE,eAAU,GAAG,OAAO,CAAC;QAOpC,IAAI,CAAC,cAAc,GAAG,MAAA,KAAK,CAAC,cAAc,mCAAI,IAAI,CAAC;QACnD,IAAI,CAAC,UAAU,GAAG,MAAA,KAAK,CAAC,UAAU,mCAAI,CAAC,CAAC;QAExC,IAAI,CAAC,WAAW,GAAG,MAAA,IAAI,CAAC,WAAW,mCAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,WAAW,CAAC,OAAO,GAAG,MAAA,IAAI,CAAC,WAAW,CAAC,OAAO,mCAAI,EAAE,CAAC;QAE1D,MAAM,SAAS,GAAG,qBAAqB,IAAI,CAAC,UAAU,EAAE,CAAC;QAEzD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAEzE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;QACvD,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,CAAC;YAE7D,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAAC;QACnE,CAAC;IACL,CAAC;CACJ;AAxBD,sCAwBC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@shapediver/sdk.geometry-api-sdk-v2",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "description": "SDK to communicate with the Geometry API version 2",
     "keywords": [
         "shapediver",

package/src/UtilsApi.ts

@@ -42,14 +42,14 @@ export class UtilsApi extends BaseAPI {
     /**
      * Upload the given file to the specified URL.
      * @param {string} url The target URL of the upload request.
-     * @param {string | Record<string, any> | ArrayBuffer | File} data The data that should be uploaded. Warning: Type `File` in Node.js might lead to problems!
+     * @param {*} data The data that should be uploaded.
      * @param {string} contentType Indicate the original media type of the resource.
      * @param {string} [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.
      * @param {*} [options] Override http request option.
      */
     public upload(
         url: string,
-        data: string | Record<string, any> | ArrayBuffer | File,
+        data: any,
         contentType: string,
         filename?: string,
         options?: RawAxiosRequestConfig
@@ -71,13 +71,13 @@ export class UtilsApi extends BaseAPI {
     /**
      * Upload the given asset to the specified ShapeDiver URL.
      * @param {string} url The target URL of the upload request.
-     * @param {string | Record<string, any> | ArrayBuffer | File} data The data that should be uploaded. Warning: Type `File` in Node.js might lead to problems!
+     * @param {*} data The data that should be uploaded.
      * @param {ResAssetUploadHeaders} headers The headers object that was returned from the request-upload call.
      * @param {*} [options] Override http request option.
      */
     public uploadAsset(
         url: string,
-        data: string | Record<string, any> | ArrayBuffer | File,
+        data: any,
         headers: ResAssetUploadHeaders,
         options?: RawAxiosRequestConfig
     ): AxiosPromise<unknown> {
@@ -98,10 +98,25 @@ export class UtilsApi extends BaseAPI {
 
     /**
      * Download from the specified URL.
+     *
+     * The response type can be controlled by setting the `responseType` in the `options` object.
      * @param {string} url The target URL of the download request.
      * @param {*} [options] Override http request option.
      */
-    public download(url: string, options?: RawAxiosRequestConfig): AxiosPromise<File> {
+    public download(
+        url: string,
+        options: { responseType: 'arraybuffer' | 'blob' } & RawAxiosRequestConfig
+    ): AxiosPromise<File>;
+    public download(
+        url: string,
+        options: { responseType: 'json' } & RawAxiosRequestConfig
+    ): AxiosPromise<Record<string, unknown>>;
+    public download(
+        url: string,
+        options: { responseType: 'text' } & RawAxiosRequestConfig
+    ): AxiosPromise<string>;
+    public download(url: string, options?: RawAxiosRequestConfig): AxiosPromise<unknown>;
+    public download(url: string, options?: RawAxiosRequestConfig): AxiosPromise<unknown> {
         const request = this.buildRequest('GET', url, undefined, options)();
         return request();
     }
@@ -109,14 +124,24 @@ export class UtilsApi extends BaseAPI {
     /**
      * Downloads a ShapeDiver export, output, or texture asset from the specified URL. The type of
      * the asset is determined by the URL and returned with the promise.
+     *
+     * The response type can be controlled by setting the `responseType` in the `options` object.
      * @param {string} url The URL of the asset to download.
      * @param {*} [options] Override http request option.
      * @throws {IllegalArgumentError} in case the URL is not a valid ShapeDiver asset URL.
      */
+    public downloadAsset(
+        url: string,
+        options: { responseType: 'arraybuffer' | 'blob' } & RawAxiosRequestConfig
+    ): [AxiosPromise<File>, 'export' | 'output' | 'texture'];
+    public downloadAsset(
+        url: string,
+        options?: RawAxiosRequestConfig
+    ): [AxiosPromise<unknown>, 'export' | 'output' | 'texture'];
     public downloadAsset(
         url: string,
         options?: RawAxiosRequestConfig
-    ): [AxiosPromise<File>, 'export' | 'output' | 'texture'] {
+    ): [AxiosPromise<unknown>, 'export' | 'output' | 'texture'] {
         let type: 'output' | 'export' | 'texture';
         this.disableAuthHeaderForShapeDiverUris(url, options);
 
@@ -130,21 +155,33 @@ export class UtilsApi extends BaseAPI {
             );
         }
 
-        return [this.download(url, options), type];
+        return [this.download(url, options) as any, type];
     }
 
     /**
      * Helper function that downloads all ShapeDiver texture URLs directly, and redirects all other
      * URLs to the `AssetsApi.downloadImage` endpoint to avoid CORS issues.
+     *
+     * The response type can be controlled by setting the `responseType` in the `options` object.
      * @param {string} sessionId The session ID.
      * @param {string} url The URL of the image to download.
      * @param {*} [options] Override http request option.
      */
+    public downloadImage(
+        sessionId: string,
+        url: string,
+        options: { responseType: 'arraybuffer' | 'blob' } & RawAxiosRequestConfig
+    ): AxiosPromise<File>;
     public downloadImage(
         sessionId: string,
         url: string,
         options?: RawAxiosRequestConfig
-    ): AxiosPromise<File> {
+    ): AxiosPromise<unknown>;
+    public downloadImage(
+        sessionId: string,
+        url: string,
+        options?: RawAxiosRequestConfig
+    ): AxiosPromise<unknown> {
         this.disableAuthHeaderForShapeDiverUris(url, options);
 
         if (
@@ -153,7 +190,7 @@ export class UtilsApi extends BaseAPI {
             directDownloadUri.test(url)
         ) {
             // Call ShapeDiver texture-asset URLs directly
-            return this.download(url, options);
+            return this.download(url, options) as any;
         } else {
             // All other source URLs are called via the download-image endpoint
             return new AssetsApi(this.configuration).downloadImage(sessionId, url, options);
@@ -371,8 +408,14 @@ export class UtilsApi extends BaseAPI {
                 reqOptions.data = serializeDataIfNeeded(data, reqOptions, configuration);
             }
 
+            // Remove the base path configuration if the URL is a full URL.
+            const configuration =
+                this.configuration && url.startsWith('http')
+                    ? new Configuration({ ...this.configuration, basePath: undefined })
+                    : this.configuration;
+
             const axiosArgs: RequestArgs = { url, options: reqOptions };
-            return createRequestFunction(axiosArgs, this.axios, basePath, this.configuration).bind(
+            return createRequestFunction(axiosArgs, this.axios, basePath, configuration).bind(
                 this.axios
             );
         };

package/src/base.ts

@@ -0,0 +1,75 @@
+import { Configuration as ClientConfig } from './client/configuration';
+import { BaseAPI as ClientBaseAPI } from './client/base';
+import { Configuration } from './configuration';
+import globalAxios, { AxiosInstance } from 'axios';
+
+/** Axios singleton instance used by all APIs by default. */
+let AXIOS: AxiosInstance | undefined;
+
+/**
+ * Overrides the `BaseAPI` class that is used by all resource APIs.
+ *
+ * NOTE: The classes are swapped out in `client/base.ts` by a script during generation.
+ *
+ * Extensions:
+ *  - Replace the global Axios instance with a custom instance.
+ *  - Extend the Axios instance by an Interceptor to handle retries on 429 and 502 status codes.
+ */
+export class BaseAPI extends ClientBaseAPI {
+    // Exposed for testing purposes.
+    readonly defaultAxios: AxiosInstance | undefined;
+
+    constructor(config?: Configuration | ClientConfig, basePath?: string) {
+        let axios: AxiosInstance | undefined;
+        if (!config || !('useCustomAxios' in config) || config.useCustomAxios) {
+            if (AXIOS === undefined)
+                AXIOS = createCustomAxiosInstance((config as any)?.maxRetries);
+            axios = AXIOS;
+        }
+        super(config, basePath, axios);
+        this.defaultAxios = axios;
+    }
+}
+
+/**
+ * Creates a custom Axios instance with a response interceptor to automatically retry requests on
+ * `429` and `502` status codes.
+ *
+ * @param {number} maxRetries - Maximum number of retry attempts before failing (default: 5).
+ * @returns A custom Axios instance with retry functionality.
+ */
+function createCustomAxiosInstance(maxRetries = 5): AxiosInstance {
+    const axios = globalAxios.create();
+
+    axios.interceptors.response.use(undefined, async (error) => {
+        const { config, response } = error;
+
+        // Exit early if no response or config is available
+        if (!response || !config) return Promise.reject(error);
+
+        // Check if retry limit is reached
+        config.retryCount = config.retryCount ?? 0;
+        if (config.retryCount >= maxRetries) return Promise.reject(error);
+
+        // Only retry for 429 or 502 status codes
+        if (response.status === 429 || response.status === 502) {
+            config.retryCount += 1;
+
+            const delay =
+                response.status === 429
+                    ? // use retry-after or default to 60s
+                      (parseInt(response.headers['retry-after'], 10) || 60) * 1000
+                    : // 1 second delay for 502 status
+                      1000;
+
+            // Delay retry and send the request again
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            return axios.request(config);
+        }
+
+        // Reject for all other error statuses
+        return Promise.reject(error);
+    });
+
+    return axios;
+}

package/src/client/api.ts

@@ -21,7 +21,8 @@ import globalAxios from 'axios';
 import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, createRequestFunction } from './common';
 import type { RequestArgs } from './base';
 // @ts-ignore
-import { BASE_PATH, COLLECTION_FORMATS, BaseAPI, RequiredError, operationServerMap } from './base';
+import { BASE_PATH, COLLECTION_FORMATS, RequiredError, operationServerMap } from './base';
+import { BaseAPI } from '../base';
 
 /**
  * Reference to the s-type parameter asset to be used.

package/src/configuration.ts

@@ -1,15 +1,48 @@
+import { RawAxiosRequestConfig } from 'axios';
 import {
     Configuration as ClientConfig,
     ConfigurationParameters as ClientConfigParams,
 } from './client/configuration';
 
-export interface ConfigurationParameters extends ClientConfigParams {}
+export interface ConfigurationParameters
+    extends Pick<ClientConfigParams, 'accessToken' | 'basePath'> {
+    /**
+     * Base options for Axios calls.
+     *
+     * @type {RawAxiosRequestConfig}
+     * @memberof ConfigurationParameters
+     */
+    baseOptions?: RawAxiosRequestConfig;
+
+    /**
+     * Enables the use of a custom Axios instance for all API requests by default, instead of the
+     * global Axios instance. This custom instance includes additional functionality to
+     * automatically retry requests on `429` and `502` status codes.
+     *
+     * Default: `true`.
+     */
+    useCustomAxios?: boolean;
+
+    /**
+     * Specifies the maximum number of automatic HTTP retries for failed requests.
+     *
+     * **Note:** This setting is only applicable when using a custom Axios instance.
+     *
+     * Default: `5`
+     */
+    maxRetries?: number;
+}
 
 export class Configuration extends ClientConfig {
-    protected readonly sdkVersion = '2.0.1'; // WARNING: This value is updated automatically!
+    protected readonly sdkVersion = '2.1.0'; // WARNING: This value is updated automatically!
+
+    public readonly useCustomAxios: boolean;
+    public readonly maxRetries: number;
 
     constructor(param: ConfigurationParameters = {}) {
         super(param);
+        this.useCustomAxios = param.useCustomAxios ?? true;
+        this.maxRetries = param.maxRetries ?? 5;
 
         this.baseOptions = this.baseOptions ?? {};
         this.baseOptions.headers = this.baseOptions.headers ?? {};