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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/management-api-client",
   "type": "module",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "private": false,
   "description": "Storyblok Management API Client",
   "author": "",
@@ -32,7 +32,7 @@
   "dependencies": {
     "async-sema": "^3.1.1",
     "ky": "^1.14.3",
-    "@storyblok/region-helper": "1.4.1"
+    "@storyblok/region-helper": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
@@ -42,7 +42,7 @@
     "tsdown": "^0.20.3",
     "tsx": "^4.20.3",
     "vitest": "^4.1.3",
-    "@storyblok/eslint-config": "0.5.1",
+    "@storyblok/eslint-config": "0.6.0",
     "@storyblok/openapi-codegen": "0.0.1"
   },
   "nx": {

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

@@ -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

@@ -1,11 +1,11 @@
-import { defineBlock, defineBlockCreate, defineBlockUpdate, defineField } from '@storyblok/schema';
+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',
-  schema: [
+  fields: [
     defineField('text', { type: 'text' }),
     defineField('image', { type: 'asset' }),
   ],
@@ -16,49 +16,23 @@ const _pageComponent = defineBlock({
   name: 'page',
   is_root: true,
   is_nestable: false,
-  schema: [
+  fields: [
     defineField('headline', { type: 'text', required: true }),
     defineField('body', { type: 'richtext' }),
-    defineField('teasers', { type: 'bloks', component_whitelist: [teaserComponent.name] }),
+    defineField('teasers', { type: 'bloks', allow: [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 () => {
+  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 wrapper Component (= Block), matching the wire shape
+      // 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');
@@ -66,19 +40,6 @@ describe('components.get response shape', () => {
   });
 });
 
-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;

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

@@ -1,44 +1,9 @@
-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({
@@ -67,24 +32,6 @@ describe('datasources type tests', () => {
 });
 
 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({
@@ -113,24 +60,6 @@ describe('datasource entries type tests', () => {
 });
 
 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({
@@ -159,24 +88,6 @@ describe('asset folders type tests', () => {
 });
 
 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({
@@ -205,24 +116,6 @@ describe('component folders type tests', () => {
 });
 
 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({
@@ -243,24 +136,6 @@ describe('internal tags type tests', () => {
 });
 
 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({
@@ -289,24 +164,6 @@ describe('presets type tests', () => {
 });
 
 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({
@@ -335,15 +192,6 @@ describe('spaces type tests', () => {
 });
 
 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({

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

@@ -1,11 +1,12 @@
-import { defineBlock, defineField, defineStoryCreate, defineStoryUpdate } from '@storyblok/schema';
-import { createManagementApiClient, type Story as StoryMapi } from '@storyblok/management-api-client';
+import { defineBlock, defineField, defineSchema, type Schema as InferSchema } from '@storyblok/schema';
+import { storyblokColorField } from '@storyblok/schema/field-plugins';
+import { createManagementApiClient, type PluginFieldValue, type Story as StoryMapi } from '@storyblok/management-api-client';
 import { describe, expectTypeOf, it } from 'vitest';
 
 // Nestable block — not a root story type
 const teaserComponent = defineBlock({
   name: 'teaser',
-  schema: [
+  fields: [
     defineField('text', { type: 'text' }),
     defineField('image', { type: 'asset' }),
   ],
@@ -18,7 +19,7 @@ const teaserComponent = defineBlock({
 const heroComponent = defineBlock({
   name: 'hero',
   is_root: true,
-  schema: [
+  fields: [
     defineField('title', { type: 'text' }),
     defineField('count', { type: 'number' }),
     // bloks field without a whitelist — resolves to nestable components only
@@ -34,12 +35,12 @@ const _pageComponent = defineBlock({
   name: 'page',
   is_root: true,
   is_nestable: false,
-  schema: [
+  fields: [
     defineField('headline', { type: 'text' }),
     defineField('body', { type: 'richtext' }),
-    defineField('teasers', { type: 'bloks', component_whitelist: [teaserComponent.name] }),
-    defineField('hero', { type: 'bloks', component_whitelist: [heroComponent.name] }),
-    defineField('blocks', { type: 'bloks', component_whitelist: [heroComponent.name, teaserComponent.name] }),
+    defineField('teasers', { type: 'bloks', allow: [teaserComponent.name] }),
+    defineField('hero', { type: 'bloks', allow: [heroComponent.name] }),
+    defineField('blocks', { type: 'bloks', allow: [heroComponent.name, teaserComponent.name] }),
   ],
   id: 0,
   created_at: '',
@@ -237,36 +238,7 @@ describe('createManagementApiClient with .withTypes()', () => {
   });
 });
 
-describe('defineStoryCreate / defineStoryUpdate combined with mapi client', () => {
-  it('should produce a defineStoryCreate result accepted by untyped stories.create', async () => {
-    const createPayload = defineStoryCreate(_pageComponent, {
-      name: 'My Page',
-      content: { headline: 'Hello' },
-    });
-
-    const client = createManagementApiClient(CLIENT_CONFIG);
-    await client.stories.create({ body: { story: createPayload } });
-  });
-
-  it('should produce a defineStoryUpdate result accepted by untyped stories.update', async () => {
-    const updatePayload = defineStoryUpdate(_pageComponent, {
-      content: { headline: 'Updated' },
-    });
-
-    const client = createManagementApiClient(CLIENT_CONFIG);
-    await client.stories.update(1, { body: { story: updatePayload } });
-  });
-
-  it('should produce a defineStoryCreate result for hero component accepted by untyped stories.create', async () => {
-    const createPayload = defineStoryCreate(heroComponent, {
-      name: 'My Hero',
-      content: { title: 'Welcome', count: 42, sections: [] },
-    });
-
-    const client = createManagementApiClient(CLIENT_CONFIG);
-    await client.stories.create({ body: { story: createPayload } });
-  });
-
+describe('withTypes() write-body narrowing', () => {
   it('should reject nestable-only component name in create body content', () => {
     const client = createManagementApiClient(CLIENT_CONFIG).withTypes<StoryblokTypes>();
     client.stories.create({
@@ -295,12 +267,44 @@ describe('defineStoryCreate / defineStoryUpdate combined with mapi client', () =
       expectTypeOf(story.content.component).toEqualTypeOf<'page' | 'hero'>();
 
       if (story.content.component === 'page') {
-        const updatePayload = defineStoryUpdate(_pageComponent, {
-          name: story.name,
-          content: { headline: story.content.headline ?? 'Default' },
-        });
-        expectTypeOf(updatePayload).toMatchTypeOf<{ name?: string | null }>();
+        expectTypeOf(story.content.headline).toEqualTypeOf<string | null | undefined>();
       }
     }
   });
 });
+
+describe('createManagementApiClient with .withTypes() — field plugins', () => {
+  const _themedComponent = defineBlock({
+    name: 'themed',
+    is_root: true,
+    fields: [
+      defineField('bg', { type: 'custom', field_type: 'storyblok-colorpicker' }),
+      defineField('legacy', { type: 'custom', field_type: 'unregistered-plugin' }),
+    ],
+  });
+  const _schema = defineSchema({
+    blocks: { themedComponent: _themedComponent },
+    fieldPlugins: { storyblokColorField },
+  });
+  type Schema = InferSchema<typeof _schema>;
+
+  it('resolves a registered custom field to the validator output merged with the plugin envelope', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG).withTypes<Schema>();
+    const result = await client.stories.get(123);
+    if (result.data?.story && result.data.story.content.component === 'themed') {
+      expectTypeOf<NonNullable<typeof result.data.story.content.bg>>().toEqualTypeOf<{
+        color: string;
+        plugin: string;
+        _uid?: string;
+      }>();
+    }
+  });
+
+  it('leaves an unregistered custom field as PluginFieldValue', async () => {
+    const client = createManagementApiClient(CLIENT_CONFIG).withTypes<Schema>();
+    const result = await client.stories.get(123);
+    if (result.data?.story && result.data.story.content.component === 'themed') {
+      expectTypeOf<NonNullable<typeof result.data.story.content.legacy>>().toEqualTypeOf<PluginFieldValue>();
+    }
+  });
+});

package/test/GUIDE.md

@@ -48,7 +48,7 @@ node packages/cli/dist/index.mjs components push \
 
 **Always push components before stories.** The CLI validates that each story's `content.component` (and any nested block components) exist in the space. Pushing stories first fails if the referenced components are not yet present.
 
-You can do the same with stories and `defineStory`. **Story filename convention:** the CLI requires files named `{slug}_{uuid}.json` where the part after the last `_` exactly matches `story.uuid` in the JSON. Use hyphens (not underscores) in UUIDs. A mismatch causes Pass 2 of the push (reference mapping + content update) to silently skip all stories.
+You can do the same with stories. **Story filename convention:** the CLI requires files named `{slug}_{uuid}.json` where the part after the last `_` exactly matches `story.uuid` in the JSON. Use hyphens (not underscores) in UUIDs. A mismatch causes Pass 2 of the push (reference mapping + content update) to silently skip all stories.
 
 ## Known quirks
 
@@ -56,4 +56,4 @@ You can do the same with stories and `defineStory`. **Story filename convention:
 - **MAPI `stories.get` takes a positional ID, not an options object:** `client.stories.get(id)` — there is no `getBySlug`. The `list` response does not include `content`; call `get(id)` for full content.
 - **MAPI client constructor uses `personalAccessToken`:** `createManagementApiClient({ personalAccessToken: '...', spaceId: ... })`.
 - **Delete methods are `delete`:** Use `client.RESOURCE.delete(id)`.
-- **Each story JSON must have a unique `id`.** `defineStory` defaults `id` to `1`. If multiple story files share the same `id`, the CLI's manifest maps all of them to the same `old_id` entry, causing "slug already taken" errors.
+- **Each story JSON must have a unique `id`.** If multiple story files share the same `id`, the CLI's manifest maps all of them to the same `old_id` entry, causing "slug already taken" errors.