Geometry Backend SDK TypeScript - Migration Guide

Migrating from Version 3.x.x to 4.x.x (28/07/2026)

Overview

Version 4 replaces Axios with the native Fetch API. This is a breaking change in the HTTP layer: Axios options, response objects, custom Axios instances, and Axios error handling must be replaced with their Fetch equivalents.

The Geometry Backend API and DTO data remain unchanged. Most migration work concerns request configuration, response handling, and errors.

Fetch runtime

Install the v4 release:

Bash

npm install @shapediver/sdk.geometry-api-sdk-v2@^4

Version 4 no longer includes Axios. The runtime must provide fetch, Request, Response, Headers, Blob, and related Fetch APIs. Modern browsers and Node.js 18+ provide them. In another environment, pass a Fetch-compatible function through fetchApi:

TypeScript

const config = new Configuration({
  basePath: "https://sdeuc1.eu-central-1.shapediver.com",
  accessToken,
  fetchApi: customFetchImplementation    // Optional: Only needed in older or special environments
});

API options

baseOptions and per-request RawAxiosRequestConfig are replaced by Fetch-compatible configuration:

headers for common headers
fetchApi for a custom transport
middleware for request, response, and transport-error hooks
queryParamsStringify for custom query serialization

Per-call overrides are RequestInit values passed as the final argument:

Version 3

TypeScript

const config = new Configuration({
  basePath,
  accessToken,
  baseOptions: { headers: { "X-Correlation-Id": correlationId } },
});

await new ModelApi(config).getModel("model-id", {
  headers: { "X-Request-Mode": "preview" },
});

Version 4

TypeScript

const config = new Configuration({
  basePath,
  accessToken,
  headers: { "X-Correlation-Id": correlationId },
});

await new ModelApi(config).getModel("model-id", {
  headers: { "X-Request-Mode": "preview" },
});

The SDK continues to retry HTTP 429 and 502 responses automatically. Set maxRetries to change the maximum; transport failures are not retried by this built-in mechanism.

API results

Generated resource API methods now resolve to parsed DTOs directly instead of Axios responses. Remove .data from ordinary calls.

Version 3

TypeScript

const response = await new ModelApi(config).getModel("model-id");
const model = response.data;
const status = response.status;

Version 4

TypeScript

const model = await new ModelApi(config).getModel("model-id");
const modelId = model.model.id;

If the raw HTTP response is required, use the generated *Raw method. Its result provides the native response through raw; call value() to read the parsed DTO:

TypeScript

const result = await new ModelApi(config).getModelRaw({ modelId: "model-id" });
const status = result.raw.status;
const model = await result.value();

Utility functions

UtilsApi upload and download helpers now use native Fetch types. They return a Response (and downloadImage returns a Blob) instead of an Axios response with data. Replace Axios's responseType with a Fetch body reader:

Version 3

TypeScript

const response = await new UtilsApi(config).download(assetUrl, {
  responseType: "arraybuffer",
});
const bytes = response.data;

Version 4

TypeScript

const response = await new UtilsApi(config).download(assetUrl);
const bytes = await response.arrayBuffer();
// Or: await response.blob(), response.text(), or response.json()

For uploads, pass a Fetch-compatible body such as ArrayBuffer, Blob, FormData, URLSearchParams, or a string, and provide a respective contentType.

Errors

The public error-handling pattern is unchanged. processError() still normalizes request and response failures to RequestError and ResponseError, which both extend SdGeometryError. Existing instanceof checks can therefore be retained.

The implementation underneath has changed: v3 processes Axios request/response errors, while v4 processes the generated Fetch response and transport errors. Native Fetch itself does not reject for an HTTP error status, but SDK API methods throw an internal response error for non-2xx responses. Generic setup errors remain ordinary Error objects and are not converted to SdGeometryError.

Version 3 and 4

TypeScript

import {
  processError,
  SdGeometryError,
  RequestError,
  ResponseError,
} from "@shapediver/sdk.geometry-api-sdk-v2";

try {
  await sdk.model.get("model-id");
} catch (err) {
  const e = await processError(err);

  if (e instanceof SdGeometryError) {
    // Base class for all custom ShapeDiver errors.
  }
  if (e instanceof RequestError) {
    // The request was made but no response was received.
  }
  if (e instanceof ResponseError) {
    // The server responded with a status outside the 2xx range.
  }
}

Migrating from Version 1.x.x to 2.x.x (03/11/2024)

Overview

Version 2 of the Geometry Backend API SDK has been fully re-engineered to provide greater control over request handling and response processing. The new SDK allows direct interaction with the underlying Axios library, configurable on a per-request basis. This redesign introduces breaking changes across the SDK, including renaming many types and reworking the core interaction patterns.

Data Transfer Objects (DTOs)

To maintain compatibility, the structure and property names of all Data Transfer Objects (DTOs) remain unchanged. However, the interface names have been updated for consistency. Refer to the Geometry API documentation for a full list of DTOs and their details by endpoint.

Resource Management

Previously, the SDK centered around a single client instance for all resources. For example:

TypeScript

import { create } from "@shapediver/sdk.geometry-api-sdk-v2";

// Client instance
const sdk = create("https://sdeuc1.eu-central-1.shapediver.com");

// Resource calls
await sdk.session.init("ticket");
await sdk.model.get("model-id");
await sdk.export.compute("session-id", {});

With Version 2, each resource API is instantiated directly and managed independently. This approach allows customization through a Configuration instance for each API. Additional RawAxiosRequestConfig options can be provided per individual request:

TypeScript

Copy code
import {
  Configuration,
  SessionApi,
  ModelApi,
  ExportApi,
} from "@shapediver/sdk.geometry-api-sdk-v2";

// General config
const config = new Configuration({
  basePath: "https://sdeuc1.eu-central-1.shapediver.com",
});

// Resource instantiation and calling
await new SessionApi(config).createSessionByTicket("ticket");
await new ModelApi(config).getModel("model-id");
await new ExportApi(config).computeExports("session-id", {});

// Custom configuration for a single call
await new ExportApi(config).computeExports(
  "session-id",
  {},
  { headers: { "Content-Type": "custom-content-type" } }
);

Return Objects

In Version 2, each resource API call returns an AxiosPromise object, which includes extensive information about both the request and the response. This allows direct access to details such as HTTP status, parsed response data, and headers, providing greater flexibility for handling responses. However, it introduces a small change in how resources are accessed:

TypeScript

// Example on how to extract information from the response object
const res = await new SessionApi(config).createSessionByTicket("ticket");
const status = res.status;       // HTTP status code
const headers = res.headers;     // Response headers
const session = res.data;        // Parsed response data
const request = res.request;     // Various information about the request made

// Inline access to parsed data
const model = (await new ModelApi(config).getModel("model-id")).data;

Utility Functions

Version 2 retains (and expands on) the utility functions from Version 1, with a restructured organization:

HTTP-related utilities are now encapsulated within the UtilsApi class, supporting both global and per-call configuration via Configuration and RawAxiosRequestConfig.
Other utility functions, such as extractFileInfo, exists, and processError, are provided as standalone methods.

Error Handling

Version 1 SDK errors included ShapeDiverError, ShapeDiverRequestErrorCore, and ShapeDiverResponseError. Type guards allowed distinguishing between these errors.

In Version 2, the SDK adopts AxiosError for better integration with Axios, providing detailed request and response data. For simpler handling of API-specific errors, the SDK introduces processError, which returns instances of:

SdError (analogous to ShapeDiverError)
SdRequestError (similar to ShapeDiverRequestErrorCore)
SdResponseError (similar to ShapeDiverResponseError)

Use instanceof checks to easily identify these error types. See the README for further information.