@storyblok/management-api-client 1.0.0-alpha.1 → 1.0.0-alpha.2

package/playground/integration-tests/README.md

@@ -0,0 +1,24 @@
+# @storyblok/mapi-integration-tests
+
+Integration tests for [`@storyblok/management-api-client`](../../) paired with [`@storyblok/schema`](../../../schema).
+
+This playground exists so the management-api-client package itself stays free of a runtime dependency on `@storyblok/schema`, while still letting us verify that the two packages line up.
+
+## Type tests
+
+`test/types/*.test-d.ts` assert that `defineBlock` / `defineX*` payloads from `@storyblok/schema` are assignable to the corresponding MAPI request bodies, and that `.withTypes()` narrows responses correctly. They run in CI:
+
+```bash
+pnpm --filter @storyblok/mapi-integration-tests test
+pnpm --filter @storyblok/mapi-integration-tests test:types
+```
+
+## End-to-end tests
+
+`test/specs/*.spec.e2e.ts` exercise a real round-trip against the Storyblok MAPI using a personal access token. Run manually only:
+
+```bash
+pnpm --filter @storyblok/mapi-integration-tests test:e2e
+```
+
+Requires `.env.qa-engineer-manual` at the repo root with `STORYBLOK_TOKEN` and `STORYBLOK_SPACE_ID`.

package/playground/integration-tests/eslint.config.js

@@ -0,0 +1,5 @@
+import { storyblokLintConfig } from '@storyblok/eslint-config';
+
+export default storyblokLintConfig({}, {
+  ignores: ['**/*.md'],
+});

package/playground/integration-tests/node_modules/.bin/eslint

@@ -0,0 +1,16 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../eslint/bin/eslint.js" "$@"
+else
+  exec node  "$basedir/../eslint/bin/eslint.js" "$@"
+fi

package/playground/integration-tests/node_modules/.bin/tsc

@@ -0,0 +1,16 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/playground/integration-tests/node_modules/.bin/tsserver

@@ -0,0 +1,16 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/playground/integration-tests/node_modules/.bin/vitest

@@ -0,0 +1,16 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/playground/integration-tests/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@storyblok/mapi-integration-tests",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Integration tests for @storyblok/management-api-client paired with @storyblok/schema",
+  "scripts": {
+    "test": "vitest run",
+    "test:types": "tsc --noEmit --skipLibCheck",
+    "test:e2e": "vitest run -c vitest.config.e2e.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "devDependencies": {
+    "@storyblok/eslint-config": "workspace:*",
+    "@storyblok/management-api-client": "workspace:*",
+    "@storyblok/schema": "workspace:*",
+    "@types/node": "^24.1.0",
+    "dotenv": "^17.3.1",
+    "eslint": "^9.39.2",
+    "typescript": "5.8.3",
+    "vitest": "^4.1.3"
+  }
+}

package/{test → playground/integration-tests/test}/setup.e2e.ts

@@ -1,7 +1,7 @@
-import { config } from 'dotenv';
 import { resolve } from 'node:path';
+import { config } from 'dotenv';
 
-config({ path: resolve(import.meta.dirname, '../../../.env.qa-engineer-manual') });
+config({ path: resolve(import.meta.dirname, '../../../../../.env.qa-engineer-manual') });
 
 if (!process.env.STORYBLOK_TOKEN || !process.env.STORYBLOK_SPACE_ID) {
   throw new Error(

package/{test → playground/integration-tests/test}/specs/mapi-round-trip.spec.e2e.ts

@@ -9,7 +9,7 @@
  *  4. Zod schemas generated from the OpenAPI spec accept real API responses.
  *
  * Run manually (never in CI):
- *   pnpm --filter @storyblok/management-api-client test:e2e
+ *   pnpm --filter @storyblok/mapi-integration-tests test:e2e
  *
  * Requires .env.qa-engineer-manual at the repo root with:
  *   STORYBLOK_TOKEN=<personal-access-token>

package/playground/integration-tests/test/types/components.test-d.ts

@@ -0,0 +1,113 @@
+import { defineBlock, defineBlockCreate, defineBlockUpdate, defineField } from '@storyblok/schema';
+import { type Component as ComponentMapi, createManagementApiClient } from '@storyblok/management-api-client';
+import { describe, expectTypeOf, it } from 'vitest';
+
+// Nestable block — not a root story type
+const teaserComponent = defineBlock({
+  name: 'teaser',
+  schema: [
+    defineField('text', { type: 'text' }),
+    defineField('image', { type: 'asset' }),
+  ],
+});
+
+// Root content type, not nestable
+const _pageComponent = defineBlock({
+  name: 'page',
+  is_root: true,
+  is_nestable: false,
+  schema: [
+    defineField('headline', { type: 'text', required: true }),
+    defineField('body', { type: 'richtext' }),
+    defineField('teasers', { type: 'bloks', component_whitelist: [teaserComponent.name] }),
+  ],
+});
+
+const CLIENT_CONFIG = { personalAccessToken: 'test-token', spaceId: 12345 };
+
+describe('components.create body type compatibility', () => {
+  it('should produce a defineBlockCreate result assignable to components.create body', () => {
+    const createPayload = defineBlockCreate({
+      name: 'article',
+      schema: {
+        title: { type: 'text', pos: 1 },
+      },
+    });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['components']['create']>[0]['body'];
+    type ComponentCreateInput = NonNullable<CreateBody['component']>;
+
+    expectTypeOf(createPayload).toExtend<ComponentCreateInput>();
+  });
+
+  it('should produce a defineBlockUpdate result assignable to components.update body', () => {
+    const updatePayload = defineBlockUpdate({
+      display_name: 'Article',
+    });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['components']['update']>[1]['body'];
+    type ComponentUpdateInput = NonNullable<UpdateBody['component']>;
+
+    expectTypeOf(updatePayload).toExtend<ComponentUpdateInput>();
+  });
+});
+
+describe('components.get response shape', () => {
+  it('should return a Component from components.get matching the wire shape', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.components.get(123);
+
+    if (result.data?.component) {
+      // components.get() returns the wrapper Component (= Block), matching the wire shape
+      expectTypeOf(result.data.component.id).toEqualTypeOf<ComponentMapi['id']>();
+      expectTypeOf(result.data.component.name).toEqualTypeOf<ComponentMapi['name']>();
+      expectTypeOf(result.data.component).toHaveProperty('schema');
+    }
+  });
+});
+
+describe('components.create body type rejection', () => {
+  it('should reject a component create payload with wrong schema field type', () => {
+    const createPayload = defineBlockCreate({
+      name: 'article',
+      schema: {
+        // @ts-expect-error: schema value must be a field definition, not a string
+        title: 'invalid',
+      },
+    });
+    void createPayload;
+  });
+});
+
+describe('defineBlock result used in .withTypes() interface', () => {
+  interface StoryblokTypes {
+    components: typeof _pageComponent | typeof teaserComponent;
+  }
+
+  it('should narrow story content to page or teaser after withTypes', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG).withTypes<StoryblokTypes>();
+    const result = await client.stories.get(123);
+
+    if (result.data?.story) {
+      // Only page is a root component (is_root: true); teaser is nestable-only
+      expectTypeOf(result.data.story.content.component).toEqualTypeOf<'page'>();
+    }
+  });
+
+  it('should narrow bloks field on page to whitelisted teasers', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG).withTypes<StoryblokTypes>();
+    const result = await client.stories.get(123);
+
+    if (result.data?.story) {
+      const story = result.data.story;
+      if (story.content.component === 'page') {
+        if (story.content.teasers) {
+          for (const teaser of story.content.teasers) {
+            // teasers whitelists only the teaser component
+            expectTypeOf(teaser.component).toEqualTypeOf<'teaser'>();
+          }
+        }
+      }
+    }
+  });
+});

package/playground/integration-tests/test/types/resources.test-d.ts

@@ -0,0 +1,364 @@
+import {
+  defineAssetFolderCreate,
+  defineAssetFolderUpdate,
+  defineBlockFolderCreate,
+  defineBlockFolderUpdate,
+  defineDatasourceCreate,
+  defineDatasourceEntryCreate,
+  defineDatasourceEntryUpdate,
+  defineDatasourceUpdate,
+  defineInternalTagCreate,
+  defineInternalTagUpdate,
+  definePresetCreate,
+  definePresetUpdate,
+  defineSpaceCreate,
+  defineSpaceUpdate,
+  defineUserUpdate,
+} from '@storyblok/schema';
+import { createManagementApiClient } from '@storyblok/management-api-client';
+import { describe, expectTypeOf, it } from 'vitest';
+
+const CLIENT_CONFIG = { personalAccessToken: 'test-token', spaceId: 12345 };
+
+describe('datasources type tests', () => {
+  it('should produce a defineDatasourceCreate result assignable to datasources.create body', () => {
+    const payload = defineDatasourceCreate({ name: 'Categories', slug: 'categories' });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['datasources']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['datasource']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineDatasourceUpdate result assignable to datasources.update body', () => {
+    const payload = defineDatasourceUpdate({ name: 'Updated Categories' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['datasources']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['datasource']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return datasource in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasources.create({
+      body: { datasource: { name: 'Test', slug: 'test' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasource');
+    }
+  });
+
+  it('should return datasource in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasources.get(1);
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasource');
+    }
+  });
+
+  it('should return datasources array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasources.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasources');
+    }
+  });
+});
+
+describe('datasource entries type tests', () => {
+  it('should produce a defineDatasourceEntryCreate result assignable to datasourceEntries.create body', () => {
+    const payload = defineDatasourceEntryCreate({ name: 'red', value: '#ff0000', datasource_id: 42 });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['datasourceEntries']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['datasource_entry']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineDatasourceEntryUpdate result assignable to datasourceEntries.update body', () => {
+    const payload = defineDatasourceEntryUpdate({ value: '#00ff00' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['datasourceEntries']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['datasource_entry']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return datasource_entry in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasourceEntries.create({
+      body: { datasource_entry: { name: 'red', value: '#ff0000', datasource_id: 42 } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasource_entry');
+    }
+  });
+
+  it('should return datasource_entry in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasourceEntries.get(1);
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasource_entry');
+    }
+  });
+
+  it('should return datasource_entries array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.datasourceEntries.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('datasource_entries');
+    }
+  });
+});
+
+describe('asset folders type tests', () => {
+  it('should produce a defineAssetFolderCreate result assignable to assetFolders.create body', () => {
+    const payload = defineAssetFolderCreate({ name: 'Images' });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['assetFolders']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['asset_folder']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineAssetFolderUpdate result assignable to assetFolders.update body', () => {
+    const payload = defineAssetFolderUpdate({ name: 'Updated Images' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['assetFolders']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['asset_folder']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return asset_folder in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.assetFolders.create({
+      body: { asset_folder: { name: 'Photos' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('asset_folder');
+    }
+  });
+
+  it('should return asset_folder in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.assetFolders.get(1);
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('asset_folder');
+    }
+  });
+
+  it('should return asset_folders array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.assetFolders.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('asset_folders');
+    }
+  });
+});
+
+describe('component folders type tests', () => {
+  it('should produce a defineBlockFolderCreate result assignable to componentFolders.create body', () => {
+    const payload = defineBlockFolderCreate({ name: 'Layout' });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['componentFolders']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['component_group']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineBlockFolderUpdate result assignable to componentFolders.update body', () => {
+    const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['componentFolders']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['component_group']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return component_group in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.componentFolders.create({
+      body: { component_group: { name: 'Layout' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('component_group');
+    }
+  });
+
+  it('should return component_group in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.componentFolders.get(1);
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('component_group');
+    }
+  });
+
+  it('should return component_groups array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.componentFolders.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('component_groups');
+    }
+  });
+});
+
+describe('internal tags type tests', () => {
+  it('should produce a defineInternalTagCreate result assignable to internalTags.create body', () => {
+    const payload = defineInternalTagCreate({ name: 'hero', object_type: 'asset' });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['internalTags']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['internal_tag']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineInternalTagUpdate result assignable to internalTags.update body', () => {
+    const payload = defineInternalTagUpdate({ name: 'hero-image' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['internalTags']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['internal_tag']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return internal_tag in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.internalTags.create({
+      body: { internal_tag: { name: 'hero' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('internal_tag');
+    }
+  });
+
+  it('should return internal_tags array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.internalTags.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('internal_tags');
+    }
+  });
+});
+
+describe('presets type tests', () => {
+  it('should produce a definePresetCreate result assignable to presets.create body', () => {
+    const payload = definePresetCreate({ name: 'Hero Dark', component_id: 42 });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['presets']['create']>[0]['body'];
+    type InnerType = NonNullable<CreateBody['preset']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a definePresetUpdate result assignable to presets.update body', () => {
+    const payload = definePresetUpdate({ name: 'Hero Light' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['presets']['update']>[1]['body'];
+    type InnerType = NonNullable<UpdateBody['preset']>;
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return preset in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.presets.create({
+      body: { preset: { name: 'Hero Dark', component_id: 42 } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('preset');
+    }
+  });
+
+  it('should return preset in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.presets.get(1);
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('preset');
+    }
+  });
+
+  it('should return presets array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.presets.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('presets');
+    }
+  });
+});
+
+describe('spaces type tests', () => {
+  it('should produce a defineSpaceCreate result assignable to spaces.create body', () => {
+    const payload = defineSpaceCreate({ name: 'My New Space' });
+
+    type CreateBody = Parameters<ReturnType<typeof createManagementApiClient>['spaces']['create']>[0]['body'];
+    type InnerType = CreateBody['space'];
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should produce a defineSpaceUpdate result assignable to spaces.update body', () => {
+    const payload = defineSpaceUpdate({ name: 'Updated Space Name' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['spaces']['update']>[0]['body'];
+    type InnerType = UpdateBody['space'];
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return space in response from create', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.spaces.create({
+      body: { space: { name: 'Test Space' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('space');
+    }
+  });
+
+  it('should return space in response from get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.spaces.get();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('space');
+    }
+  });
+
+  it('should return spaces array in response from list', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.spaces.list();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('spaces');
+    }
+  });
+});
+
+describe('users type tests', () => {
+  it('should produce a defineUserUpdate result assignable to users.updateMe body', () => {
+    const payload = defineUserUpdate({ firstname: 'Jane', lastname: 'Doe' });
+
+    type UpdateBody = Parameters<ReturnType<typeof createManagementApiClient>['users']['updateMe']>[0]['body'];
+    type InnerType = UpdateBody['user'];
+
+    expectTypeOf(payload).toExtend<InnerType>();
+  });
+
+  it('should return user in response from updateMe', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.users.updateMe({
+      body: { user: { firstname: 'Jane' } },
+    });
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('user');
+    }
+  });
+
+  it('should return user in response from me', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.users.me();
+    if (result.data) {
+      expectTypeOf(result.data).toHaveProperty('user');
+    }
+  });
+});