npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@shapediver/sdk.geometry-api-sdk-v2

v2.3.0

Published

SDK to communicate with the Geometry API version 2

Downloads

4,051

Readme

GeometryBackendSdkTypeScript

:warning: You might be looking for the v1 docs - Migration Guide.

ShapeDiver is a cloud platform for building online applications based on parametric 3D files made with Rhinoceros 3D and Grasshopper.

Using the ShapeDiver Geometry Backend API allows access to ShapeDiver models without using the ShapeDiver Viewer. This SDK provides functionality to communicate with the Geometry Backend API version 2, and includes type hints describing request and response data objects. See the API documentation for more details.

Authentication

The authentication system for the Geometry Backend API is based on ticket objects and JWT tokens, which are handled by the ShapeDiver Platform. You can obtain tickets and JWT tokens by:

An SDK for the ShapeDiver Platform API will be released soon.

When obtaining a ticket for your model from the ShapeDiver Platform, please be aware that you will need a ticket for backend access, since you are accessing the Geometry Backend API from an arbitrary client application that is not a web browser. For more details see the ShapeDiver Help Center developer settings.

Base URL

The base URL to use depends on which ShapeDiver Geometry Backend System your model was uploaded to. You can find the base URL in your model's dashboard on the ShapeDiver Platform, it is also called the model view url.

Usage - Ticket only

import {
  Configuration,
  SessionApi
} from '@shapediver/sdk.geometry-api-sdk-v2';

(async function () {
    // Please see above on how to obtain a ticket
    const ticket = '8b23fae66cf535719a9ec797e390208b2003e3cfc894b7624ada2f6894515f8836a4-66303337623538322d34386';

    // Initialize the SDK configuration instance by providing the base URL
    const config = new Configuration({
      basePath: 'https://sdeuc1.eu-central-1.shapediver.com'
    });

    // Initialize a new session using the ticket.
    const res = (
      await new SessionApi(config).createSessionByTicket(ticket)
    ).data;

    console.log(res);
})();

Usage - Ticket and JWT

It is possible to configure your ShapeDiver models such that JWT tokens are required to communicate with them, which provides a strong authorisation mechanism. In this case you will need to use the ShapeDiver Platform API to obtain a JWT token for your model on demand:

import {
  Configuration,
  SessionApi
} from '@shapediver/sdk.geometry-api-sdk-v2';

(async function () {
    // Please see above on how to obtain a ticket and a JWT.
    const jwt = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikp1c3QgYSB0ZXN0IiwiaWF0IjoxNjE4OTExMjcxLCJleHAiOjE2MTg5MTQ4OTcsImp0aSI6IjYzMjA3ODE3LWJiNWQtNDY3Zi04NzRkLWM4N2EyYzAxYmZlZCJ9.S5Ps_Fx5p6aJxdBOJMBKgpf2SIlp--6kkIZU55tiqEg';
    const ticket = '8b23fae66cf535719a9ec797e390208b2003e3cfc894b7624ada2f6894515f8836a4-66303337623538322d34386';

    // Initialize the SDK client instance by providing the base URL
    const config = new Configuration({
        basePath: 'https://sdeuc1.eu-central-1.shapediver.com',
        accessToken: jwt,
    });

    // Initialize a new session using the ticket.
    const res = (
      await new SessionApi(config).createSessionByTicket(ticket)
    ).data;

    console.log(res);
})();

Handling Errors

The SDK provides a helper function to extract ShapeDiver error information from an AxiosError:

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

try {
  sdk.model.get("be5d4ce5-f76d-417d-8496-1f038e6f0cab")
} catch (err) {
  const e = processError(err);

  if (e instanceof SdGeometryError) {
    /*
     * Generic ShapeDiver error.
     *
     * Generic errors are the base class of all custom ShapeDiver errors, like RequestError,
     * ResponseError, IllegalArgumentError, TimeoutError, etc.
     *
     * Warning:
     *  Generic Axios errors (non-request/response errors) that are thrown when setting up the
     *  request are not converted into a SdGeometryError!
     */
  }

  if (e instanceof RequestError) {
    /*
     * Wrapper around an Axios request error.
     *
     * In this case, the request was made but no response was received.
     */
  }

  if (e instanceof ResponseError) {
    /*
     * Wrapper around an Axios response error.
     *
     * In this case, the request was made and the server responded with a status code that falls
     * out of the range of 2xx.
     */
  }
}

Examples

Making Changes & Contributing

Most of the code in this repository has been generated via the OpenAPI Generator. The specification of the Geometry Backend API version 2 can be found in the ShapeDiver OAS repository. Additionally, we have added wrappers and utility functions to improve overall usability.

Setup

This project is written in TypeScript and uses PNPM as a dependency manager. Project-specific commands are handled either via NPM or just, so make sure that both tools are installed. To get an overview of all available commands run npm run -l and just --list.

Run the following commands to install all dependencies:

npm run init

Generate Code

To re-generate the code from the ShapeDiver OAS file, you need to install version 7 of the OpenAPI Generator. We recommend installing it as a global NPM package:

npm i -g openapi-generator

Afterwards, update the local file ./oas_spec.yaml and generate the new code via just generate <version>. The version argument represents the respective Git tag from ShapeDiver OAS. For instance, use version "1.0.0" when targeting the Git tag "[email protected]".

Alternatively, the client can be generated from a local file. Check out the ShapeDiver OAS repository and run just generate local.

Release

Before releasing a new versions of this package ensure that you have configured everything in your ~/.npmrc file. Afterwards, run npm run publish and follow the CLI to build, publish, and commit a new version of the TypeScript package. Before releasing a new version of this package, ensure that your ~/.npmrc file is fully configured. Then, run npm run publish and follow the CLI instructions to build, publish, and commit the new version of the TypeScript package.

Test

Unit and integration tests can be executed via npm run test. However, should you want to run only a single test file then run npx jest -i --forceExit <path> within the package instead.

Versioning

We take care to provide backwards compatibility for all older versions. However, new features might be limited to newer API versions. Therefore, we recommend always using the newest API version out there.

Support

If you have questions, please use the ShapeDiver Help Center.

You can find out more about ShapeDiver right here.

Licensing

This project is released under the MIT License.