🐛 [Bug]: storyblok-js-client types do not match the api response and expected method parameters

[leifmarcus]

Package

storyblok-js-client (Client SDK)

Bug Description

There seems to be a mismatch between the types assigned to the Storyblok JS Client and the API response. Additionally, the parameter typings don’t match the expected values.

Steps to Reproduce

1. setup a new node project
2. install storyblok-js-client
3. run some example requests against the management API
4. See the difference between the response and the type that is assigned

Expected Behavior

• All Response types should be aligned with the data structure, that the SDK actually returns
  -The client methods should have their parameters correctly typed to ensure that the client can be utilized without the need to add // @ts-ignore to all parameters.
• Function parameter types should enforce the correct input data, as specified in the Management API documentation: https://www.storyblok.com/docs/api/management/getting-started/

Actual Behavior

Here are some examples, but the list is not complete. As far as I can see, only stories are typed correctly. All other requests are wrongly typed.

// Some examples:
import StoryblokClient from 'storyblok-js-client';

const client = new StoryblokClient({
  oauthToken: process.env.STORYBLOK_PRIVATE_TOKEN
  // ...
});

client.get('spaces/:space-id/datasource_entries', {
  // datasource_id is not allowed here, even if it is
  // described in the documentation: 
  // https://www.storyblok.com/docs/api/management/datasource-entries/retrieve-multiple-datasource-entries
  datasource_id: '1224',
});

await client.put(`/spaces/606/datasources/91`, {
  // datasource is typed as string, even if applied according to documentation:
  // https://www.storyblok.com/docs/api/management/datasources/update-a-datasource
  datasource: {
      dimensions_attributes: [
        {
          name: 'dimension,
          entry_value: locale,
        },
      ],
    },
}


const result = await sbClient.put(`spaces/:space-id/releases/:release-id`, {
  release: {
    name: 'Updated Name',
    description: 'Updated Description',
  },
});
// what the client actually returns:
result.data.release,
// but, the return types does not include `data`.

// Essentially, all data received via the Management API, excluding stories, is incorrectly typed.

Code Sample

Environment

System:
    OS: macOS 15.6
    CPU: (10) arm64 Apple M1 Pro
    Memory: 103.09 MB / 32.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.16.0 - ~/.nvm/versions/node/v22.16.0/bin/node
    npm: 10.9.2 - ~/.nvm/versions/node/v22.16.0/bin/npm
    pnpm: 10.6.5 - ~/Library/pnpm/pnpm
  npmPackages:
    @storyblok/js: ^4.2.1 => 4.2.1 
    vue: ^3.5.20 => 3.5.20 
    storyblok-js-client: 7.1.3

Error Logs

Additional Context

Unfortunately, it’s not possible to use this SDK if you want to work with the management API or make non-story-related requests. Most of the time you need to add // @ts-ignore to make the client work as expected.

I wonder a bit, how someone could work with it in typescript.

[alvarosabu]

Hi @leifmarcus thanks for raising this. You are definitely right, the types on the js-client are far from useful, this is one of the reasons why we are planning to split the js-client into two different packages generated by an Open API spec that is in progress:

• @storyblok/management-api-client, which is in early stages of development https://www.npmjs.com/package/@storyblok/management-api-client
• Future @storyblok/content-api-client

You could potentially use the first one for better TypeScript support if you are using the management API, but be aware that it is a WIP and far from stable, although if you would like to help us with feedback on that package it would be really helpful to get it up to speed.

Let me know

[leifmarcus]

@alvarosabu, thank you! We'll check the management api client