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

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>
@@ -18,16 +18,10 @@
 
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { createManagementApiClient } from '@storyblok/management-api-client';
+import type { StoryCreate, StoryUpdate } from '@storyblok/management-api-client';
 import {
-  createStoryHelpers,
   defineBlock,
-  defineBlockCreate,
-  defineBlockFolderCreate,
-  defineDatasourceCreate,
-  defineDatasourceEntryCreate,
   defineField,
-  defineInternalTagCreate,
-  definePresetCreate,
 } from '@storyblok/schema';
 
 const token = process.env.STORYBLOK_TOKEN!;
@@ -43,7 +37,7 @@ const STORY_SLUG = `${STORY_SLUG_PREFIX}test-page`;
 
 const teaserComponent = defineBlock({
   name: `${PREFIX}teaser`,
-  schema: [
+  fields: [
     defineField('title', { type: 'text', required: true }),
     defineField('image', { type: 'asset' }),
   ],
@@ -51,21 +45,21 @@ const teaserComponent = defineBlock({
 // Level-2 container: holds teasers in its `items` bloks field (level 3)
 const sectionComponent = defineBlock({
   name: `${PREFIX}section`,
-  schema: [
+  fields: [
     defineField('title', { type: 'text' }),
-    defineField('items', { type: 'bloks', component_whitelist: [teaserComponent.name], required: true }),
+    defineField('items', { type: 'bloks', allow: [teaserComponent.name], required: true }),
   ],
 });
 const pageComponent = defineBlock({
   name: `${PREFIX}page`,
   is_root: true,
-  schema: [
+  fields: [
     defineField('headline', { type: 'text', required: true }),
     defineField('rating', { type: 'number' }),
     defineField('is_featured', { type: 'boolean' }),
     defineField('description', { type: 'richtext' }),
-    defineField('body', { type: 'bloks', component_whitelist: [teaserComponent.name, sectionComponent.name], required: true }),
-    defineField('category', { type: 'option', source: 'internal', datasource_slug: DATASOURCE_SLUG }),
+    defineField('body', { type: 'bloks', allow: [teaserComponent.name, sectionComponent.name], required: true }),
+    defineField('category', { type: 'option', source: 'internal', datasource: DATASOURCE_SLUG }),
     defineField('any_blocks', { type: 'bloks', required: true }),
   ],
 });
@@ -74,7 +68,7 @@ interface StoryblokTypes {
   components: typeof pageComponent | typeof teaserComponent | typeof sectionComponent;
 }
 
-const { defineStoryCreate, defineStoryUpdate } = createStoryHelpers().withTypes<StoryblokTypes>();
+type Blocks = StoryblokTypes['components'];
 
 const client = createManagementApiClient({
   personalAccessToken: token,
@@ -155,53 +149,50 @@ describe('schema + mapi-client MAPI round-trip', () => {
 
     // 1. Datasource + entries first — the page component schema references the datasource slug,
     //    and the MAPI validates that the datasource exists at component creation time.
-    const datasourcePayload = defineDatasourceCreate({
+    // Create payloads are plain MAPI wire objects validated by the typed client.
+    const dsRes = await client.datasources.create({ body: { datasource: {
       name: DATASOURCE_NAME,
       slug: DATASOURCE_SLUG,
-    });
-    const dsRes = await client.datasources.create({ body: { datasource: datasourcePayload } });
+    } } });
     datasourceId = dsRes.data!.datasource!.id!;
 
     for (const entry of [
-      defineDatasourceEntryCreate({ name: 'Technology', value: 'tech', datasource_id: datasourceId }),
-      defineDatasourceEntryCreate({ name: 'Design', value: 'design', datasource_id: datasourceId }),
-      defineDatasourceEntryCreate({ name: 'Business', value: 'business', datasource_id: datasourceId }),
+      { name: 'Technology', value: 'tech', datasource_id: datasourceId },
+      { name: 'Design', value: 'design', datasource_id: datasourceId },
+      { name: 'Business', value: 'business', datasource_id: datasourceId },
     ]) {
       await client.datasourceEntries.create({ body: { datasource_entry: entry } });
     }
 
     // 2. Component folder
-    const folderPayload = defineBlockFolderCreate({ name: `${PREFIX}folder` });
-    const folderRes = await client.componentFolders.create({ body: { component_group: folderPayload } });
+    const folderRes = await client.componentFolders.create({ body: { component_group: { name: `${PREFIX}folder` } } });
     componentFolderId = folderRes.data!.component_group!.id!;
     const folderUuid = folderRes.data!.component_group!.uuid;
 
     // 3. Teaser component (innermost — whitelisted by section)
-    const teaserPayload = defineBlockCreate({
+    const teaserRes = await client.components.create({ body: { component: {
       name: teaserComponent.name,
       schema: {
         title: { type: 'text', required: true, pos: 0 },
         image: { type: 'asset', pos: 1 },
       },
       component_group_uuid: folderUuid,
-    });
-    const teaserRes = await client.components.create({ body: { component: teaserPayload } });
+    } } });
     teaserComponentId = teaserRes.data!.component!.id!;
 
     // 4. Section component (level 2 — whitelists teaser, whitelisted by page)
-    const sectionPayload = defineBlockCreate({
+    const sectionRes = await client.components.create({ body: { component: {
       name: sectionComponent.name,
       schema: {
         title: { type: 'text', pos: 0 },
         items: { type: 'bloks', component_whitelist: [teaserComponent.name], pos: 1 },
       },
       component_group_uuid: folderUuid,
-    });
-    const sectionRes = await client.components.create({ body: { component: sectionPayload } });
+    } } });
     sectionComponentId = sectionRes.data!.component!.id!;
 
     // 5. Page component (level 1 — whitelists both teaser and section in body)
-    const pagePayload = defineBlockCreate({
+    const pageRes = await client.components.create({ body: { component: {
       name: pageComponent.name,
       schema: {
         headline: { type: 'text', required: true, pos: 0 },
@@ -214,30 +205,28 @@ describe('schema + mapi-client MAPI round-trip', () => {
       },
       component_group_uuid: folderUuid,
       is_root: true,
-    });
-    const pageRes = await client.components.create({ body: { component: pagePayload } });
+    } } });
     pageComponentId = pageRes.data!.component!.id!;
 
     // 5. Internal tag
-    const tagPayload = defineInternalTagCreate({ name: `${PREFIX}tag`, object_type: 'component' });
-    const tagRes = await client.internalTags.create({ body: { internal_tag: tagPayload } });
+    const tagRes = await client.internalTags.create({ body: { internal_tag: { name: `${PREFIX}tag`, object_type: 'component' } } });
     internalTagId = tagRes.data!.internal_tag!.id!;
 
     // 6. Preset for page component
-    const presetPayload = definePresetCreate({
+    const presetRes = await client.presets.create({ body: { preset: {
       name: `${PREFIX}default_page`,
       component_id: pageComponentId,
       preset: { headline: 'Default Headline', rating: 0, is_featured: false },
       description: `Default preset for ${pageComponent.name}`,
-    });
-    const presetRes = await client.presets.create({ body: { preset: presetPayload } });
+    } } });
     presetId = presetRes.data!.preset!.id!;
 
     // 8. Story: body[0]=teaser (level 2), body[1]=section{items:[teaser]} (levels 2+3)
-    const storyPayload = defineStoryCreate(pageComponent, {
+    const storyPayload: StoryCreate<Blocks> = {
       name: STORY_NAME,
       slug: STORY_SLUG,
       content: {
+        component: pageComponent.name,
         headline: 'Hello from e2e',
         rating: 42,
         is_featured: true,
@@ -269,7 +258,7 @@ describe('schema + mapi-client MAPI round-trip', () => {
           },
         ],
       },
-    });
+    };
     const storyRes = await client.stories.create({ body: { story: storyPayload } });
     storyId = storyRes.data!.story!.id!;
   });
@@ -485,10 +474,11 @@ describe('schema + mapi-client MAPI round-trip', () => {
     });
 
     it('should round-trip story update correctly', async () => {
-      const updatedPayload = defineStoryUpdate(pageComponent, {
+      const updatedPayload: StoryUpdate<Blocks> = {
         name: `${STORY_NAME} (Updated)`,
         slug: STORY_SLUG,
         content: {
+          component: pageComponent.name,
           headline: 'Updated headline',
           rating: 100,
           is_featured: false,
@@ -500,7 +490,7 @@ describe('schema + mapi-client MAPI round-trip', () => {
           category: 'design',
           any_blocks: [],
         },
-      });
+      };
 
       await client.stories.update(storyId, { body: { story: updatedPayload } });
 

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

@@ -0,0 +1,74 @@
+import { defineBlock, 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',
+  fields: [
+    defineField('text', { type: 'text' }),
+    defineField('image', { type: 'asset' }),
+  ],
+});
+
+// Root content type, not nestable
+const _pageComponent = defineBlock({
+  name: 'page',
+  is_root: true,
+  is_nestable: false,
+  fields: [
+    defineField('headline', { type: 'text', required: true }),
+    defineField('body', { type: 'richtext' }),
+    defineField('teasers', { type: 'bloks', allow: [teaserComponent.name] }),
+  ],
+});
+
+const CLIENT_CONFIG = { personalAccessToken: 'test-token', spaceId: 12345 };
+
+describe('components.get response shape', () => {
+  it('should return the wire Component (a `schema` record) from components.get', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG);
+    const result = await client.components.get(123);
+
+    if (result.data?.component) {
+      // components.get() returns the wire-shaped Component definition (a `schema`
+      // record), not the DSL `fields` block.
+      expectTypeOf(result.data.component.id).toEqualTypeOf<ComponentMapi['id']>();
+      expectTypeOf(result.data.component.name).toEqualTypeOf<ComponentMapi['name']>();
+      expectTypeOf(result.data.component).toHaveProperty('schema');
+    }
+  });
+});
+
+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,212 @@
+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 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 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 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 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 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 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 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 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');
+    }
+  });
+});