@shoppexio/builder-contracts 0.1.0

package/src/builder-contracts.test.ts

@@ -0,0 +1,405 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  BuilderEventSchema,
+  BuilderSettingsSchema,
+  PreviewMessageSchema,
+  StyleSlotsSchema,
+  ThemeManifestSchema,
+  applyManifestDefaultLayout,
+  validateBuilderSettingsAgainstManifest,
+  createBlockInstance,
+  createEmptyBuilderSettings,
+  convertLegacyThemeManifest,
+  migrateLegacyBuilderSettings,
+} from './index.ts';
+
+describe('@shoppex/builder-contracts', () => {
+  test('accepts an empty builder settings document', () => {
+    const settings = createEmptyBuilderSettings(7);
+
+    expect(BuilderSettingsSchema.parse(settings)).toEqual({
+      version: 2,
+      revision: 7,
+      theme: {
+        content: {},
+        layout: {},
+        style_slots: {},
+        pages: [],
+        terms: {},
+      },
+    });
+  });
+
+  test('rejects unknown style slots', () => {
+    const result = StyleSlotsSchema.safeParse({
+      'button.radius': { base: 10 },
+      'hero.magic.glow': true,
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('rejects invalid colors', () => {
+    const result = StyleSlotsSchema.safeParse({
+      'color.primary': 'tomato',
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('validates manifest block references', () => {
+    const result = ThemeManifestSchema.safeParse({
+      id: 'default',
+      name: 'Default',
+      version: '2.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          allowedBlocks: ['hero', 'faq'],
+          defaultBlocks: [{ type: 'hero', variant: 'split' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          variants: [{ id: 'split', label: 'Split' }],
+          settings: {
+            title: { type: 'text', label: 'Headline' },
+          },
+          exposedStyleSlots: ['button.radius'],
+        },
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('accepts preview APPLY_STATE messages', () => {
+    const settings = createEmptyBuilderSettings(3);
+    const result = PreviewMessageSchema.safeParse({
+      type: 'APPLY_STATE',
+      revision: 3,
+      state: settings,
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test('accepts preview REQUEST_READY messages', () => {
+    const result = PreviewMessageSchema.safeParse({
+      type: 'REQUEST_READY',
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test('accepts block add events', () => {
+    const result = BuilderEventSchema.safeParse({
+      id: 'evt_1',
+      type: 'block.add',
+      revision: 4,
+      createdAt: '2026-04-23T10:00:00.000Z',
+      source: 'dashboard',
+      pageId: 'home',
+      block: createBlockInstance({
+        id: 'hero-1',
+        type: 'hero',
+        settings: { title: 'New drop' },
+      }),
+      index: 0,
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test('migrates legacy content and token overrides', () => {
+    const migrated = migrateLegacyBuilderSettings(
+      {
+        theme: {
+          content: {
+            'hero.title': 'Summer sale',
+          },
+          tokens_override: {
+            'buttons.borderRadius': 12,
+            'colors.primary': '#ff5500',
+          },
+        },
+      },
+      12,
+    );
+
+    expect(migrated.revision).toBe(12);
+    expect(migrated.theme.content['hero.title']).toBe('Summer sale');
+    expect(migrated.theme.style_slots['button.radius']).toEqual({ base: 12 });
+    expect(migrated.theme.style_slots['color.primary']).toBe('#ff5500');
+  });
+
+  test('converts legacy theme manifests into the v2 manifest contract', () => {
+    const manifest = convertLegacyThemeManifest({
+      id: 'default',
+      name: 'Default Theme',
+      version: '1.0.0',
+      presets: [
+        {
+          id: 'gaming',
+          name: 'Gaming Store',
+          description: 'Gaming copy preset',
+          overrides: {
+            content: {
+              hero: {
+                title: 'Instant keys',
+              },
+            },
+          },
+        },
+      ],
+      builder: {
+        pages: [
+          {
+            id: 'home',
+            label: 'Home',
+            previewPath: '/',
+            blocks: ['hero', 'faq'],
+          },
+          {
+            id: 'contact-page',
+            label: 'Contact',
+            previewPath: '/contact',
+            blocks: [],
+            fields: [
+              { path: 'pages.contact.title', label: 'Title', defaultValue: 'Contact Us' },
+            ],
+          },
+        ],
+        blocks: {
+          hero: {
+            label: 'Hero',
+            maxInstances: 1,
+            fields: [
+              { path: 'hero.title', label: 'Title' },
+              {
+                path: 'hero.style',
+                type: 'select',
+                label: 'Hero Style',
+                options: [{ value: 'split', label: 'Split' }],
+              },
+            ],
+          },
+          faq: {
+            label: 'FAQ',
+            lists: [
+              { path: 'faq.items', label: 'FAQ Items', kind: 'faqItems' },
+            ],
+          },
+        },
+      },
+    });
+
+    expect(manifest.pages.home.allowedBlocks).toEqual(['hero', 'faq']);
+    expect(manifest.pages.home.defaultBlocks).toEqual([{ type: 'hero' }, { type: 'faq' }]);
+    expect(manifest.blocks.hero.settings['hero.title']).toMatchObject({ type: 'text', label: 'Title' });
+    expect(manifest.blocks.hero.settings['hero.style']).toMatchObject({ type: 'select' });
+    expect(manifest.blocks.faq.settings['faq.items']).toMatchObject({ type: 'list' });
+    expect(manifest.blocks['page-contact-page'].settings['pages.contact.title']).toMatchObject({ type: 'text' });
+    expect(manifest.pages['contact-page'].allowedBlocks).toEqual(['page-contact-page']);
+    expect(manifest.presets.gaming).toMatchObject({
+      label: 'Gaming Store',
+      description: 'Gaming copy preset',
+      content: {
+        'hero.title': 'Instant keys',
+      },
+    });
+  });
+
+  test('applies manifest default blocks to empty builder settings', () => {
+    const settings = applyManifestDefaultLayout(createEmptyBuilderSettings(2), {
+      id: 'default',
+      name: 'Default',
+      version: '2.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          allowedBlocks: ['hero', 'faq'],
+          defaultBlocks: [{ type: 'hero' }, { type: 'faq' }],
+        },
+      },
+      blocks: {
+        hero: { label: 'Hero', settings: {}, variants: [], exposedStyleSlots: [], presets: [] },
+        faq: { label: 'FAQ', settings: {}, variants: [], exposedStyleSlots: [], presets: [] },
+      },
+      styleSlots: {},
+      presets: {},
+    });
+
+    expect(settings.theme.layout.home.blocks.map((block) => block.type)).toEqual(['hero', 'faq']);
+    expect(settings.theme.layout.home.blocks.map((block) => block.id)).toEqual(['home-hero-1', 'home-faq-2']);
+  });
+
+  test('applies default layout for converted page-level fields', () => {
+    const manifest = convertLegacyThemeManifest({
+      id: 'classic',
+      name: 'Classic',
+      version: '1.0.0',
+      builder: {
+        pages: [
+          {
+            id: 'faq-page',
+            label: 'FAQ',
+            previewPath: '/faq',
+            fields: [
+              { path: 'pages.faq.title', label: 'Title', defaultValue: 'Questions' },
+            ],
+          },
+        ],
+        blocks: {},
+      },
+    });
+
+    const settings = applyManifestDefaultLayout(createEmptyBuilderSettings(0), manifest);
+
+    expect(settings.theme.layout['faq-page'].blocks).toHaveLength(1);
+    expect(settings.theme.layout['faq-page'].blocks[0]).toMatchObject({
+      id: 'faq-page-page-faq-page-1',
+      type: 'page-faq-page',
+      visible: true,
+    });
+  });
+
+  test('validates builder settings against the active manifest', () => {
+    const settings = BuilderSettingsSchema.parse({
+      version: 2,
+      revision: 1,
+      theme: {
+        content: {},
+        layout: {
+          home: {
+            blocks: [
+              {
+                id: 'hero-1',
+                type: 'hero',
+                variant: 'missing',
+                visible: true,
+                settings: {
+                  'hero.title': 'Launch sale',
+                  title: 'Launch sale',
+                  'hero.magic': 'not declared',
+                },
+                style_overrides: {
+                  'input.radius': { base: 10 },
+                },
+              },
+              { id: 'hero-2', type: 'hero', visible: true, settings: {} },
+              { id: 'hero-2', type: 'faq', visible: true, settings: {} },
+              { id: 'ghost-1', type: 'ghost', visible: true, settings: {} },
+            ],
+          },
+          checkout: {
+            blocks: [],
+          },
+        },
+        style_slots: {},
+        pages: [],
+        terms: {},
+      },
+    });
+
+    const issues = validateBuilderSettingsAgainstManifest(settings, {
+      id: 'default',
+      name: 'Default',
+      version: '2.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          allowedBlocks: ['hero'],
+          defaultBlocks: [{ type: 'hero' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          settings: {
+            'hero.title': { type: 'text', label: 'Title' },
+          },
+          variants: [{ id: 'split', label: 'Split' }],
+          exposedStyleSlots: ['button.radius'],
+          maxInstances: 1,
+          presets: [],
+        },
+        faq: {
+          label: 'FAQ',
+          settings: {},
+          variants: [],
+          exposedStyleSlots: [],
+          presets: [],
+        },
+      },
+      styleSlots: {},
+      presets: {},
+    });
+
+    expect(issues.map((issue) => issue.code)).toContain('unknown_page');
+    expect(issues.map((issue) => issue.code)).toContain('duplicate_block_id');
+    expect(issues.map((issue) => issue.code)).toContain('unknown_block_type');
+    expect(issues.map((issue) => issue.code)).toContain('block_not_allowed');
+    expect(issues.map((issue) => issue.code)).toContain('too_many_block_instances');
+    expect(issues.map((issue) => issue.code)).toContain('unknown_block_variant');
+    expect(issues.map((issue) => issue.code)).toContain('unknown_block_setting');
+    expect(issues.map((issue) => issue.code)).toContain('unexposed_style_slot');
+  });
+
+  test('accepts full and short block setting keys declared by the manifest', () => {
+    const settings = BuilderSettingsSchema.parse({
+      version: 2,
+      revision: 1,
+      theme: {
+        content: {},
+        layout: {
+          home: {
+            blocks: [
+              {
+                id: 'hero-1',
+                type: 'hero',
+                visible: true,
+                settings: {
+                  'hero.title': 'Launch sale',
+                  title: 'Launch sale',
+                },
+              },
+            ],
+          },
+        },
+        style_slots: {},
+        pages: [],
+        terms: {},
+      },
+    });
+
+    const issues = validateBuilderSettingsAgainstManifest(settings, {
+      id: 'default',
+      name: 'Default',
+      version: '2.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          allowedBlocks: ['hero'],
+          defaultBlocks: [{ type: 'hero' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          settings: {
+            'hero.title': { type: 'text', label: 'Title' },
+          },
+          variants: [],
+          exposedStyleSlots: [],
+          presets: [],
+        },
+      },
+      styleSlots: {},
+      presets: {},
+    });
+
+    expect(issues).toEqual([]);
+  });
+});

package/src/builder-settings.ts

@@ -0,0 +1,85 @@
+import * as z from 'zod/v4';
+import { StyleSlotsSchema } from './style-slots.ts';
+
+export const BUILDER_SETTINGS_VERSION = 2;
+
+export const PageIdSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_/]*$/);
+export type PageId = z.infer<typeof PageIdSchema>;
+
+export const BlockInstanceIdSchema = z.string().min(1);
+export type BlockInstanceId = z.infer<typeof BlockInstanceIdSchema>;
+
+export const BlockTypeSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_.]*$/);
+export type BlockType = z.infer<typeof BlockTypeSchema>;
+
+export const BlockInstanceSchema = z
+  .object({
+    id: BlockInstanceIdSchema,
+    type: BlockTypeSchema,
+    variant: z.string().min(1).optional(),
+    visible: z.boolean().default(true),
+    settings: z.record(z.string().min(1), z.unknown()).default({}),
+    style_overrides: StyleSlotsSchema.optional(),
+  })
+  .strict();
+export type BlockInstance = z.infer<typeof BlockInstanceSchema>;
+
+export const PageLayoutSchema = z
+  .object({
+    blocks: z.array(BlockInstanceSchema).default([]),
+  })
+  .strict();
+export type PageLayout = z.infer<typeof PageLayoutSchema>;
+
+export const CustomPageSchema = z
+  .object({
+    id: PageIdSchema,
+    title: z.string().min(1),
+    slug: z.string().min(1).regex(/^[a-z0-9][a-z0-9-_/]*$/),
+    visible: z.boolean().default(true),
+    layout: PageLayoutSchema.default({ blocks: [] }),
+    seo: z
+      .object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type CustomPage = z.infer<typeof CustomPageSchema>;
+
+export const TermsSchema = z
+  .object({
+    termsOfService: z.string().optional(),
+    privacyPolicy: z.string().optional(),
+    refundPolicy: z.string().optional(),
+    imprint: z.string().optional(),
+  })
+  .strict()
+  .default({});
+export type Terms = z.infer<typeof TermsSchema>;
+
+export const BuilderThemeStateSchema = z
+  .object({
+    content: z.record(z.string().min(1), z.unknown()).default({}),
+    layout: z.record(PageIdSchema, PageLayoutSchema).default({}),
+    style_slots: StyleSlotsSchema.default({}),
+    pages: z.array(CustomPageSchema).default([]),
+    terms: TermsSchema,
+  })
+  .strict();
+export type BuilderThemeState = z.infer<typeof BuilderThemeStateSchema>;
+
+export const BuilderSettingsSchema = z
+  .object({
+    version: z.literal(BUILDER_SETTINGS_VERSION),
+    revision: z.number().int().nonnegative(),
+    theme: BuilderThemeStateSchema,
+  })
+  .strict();
+export type BuilderSettings = z.infer<typeof BuilderSettingsSchema>;
+
+export function parseBuilderSettings(input: unknown): BuilderSettings {
+  return BuilderSettingsSchema.parse(input);
+}

package/src/events.ts

@@ -0,0 +1,121 @@
+import * as z from 'zod/v4';
+import { BlockInstanceSchema, CustomPageSchema, PageIdSchema } from './builder-settings.ts';
+import { StyleSlotIdSchema } from './style-slots.ts';
+
+const EventBaseSchema = z
+  .object({
+    id: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    createdAt: z.string().datetime(),
+    source: z.enum(['dashboard', 'preview', 'migration', 'agent']),
+  })
+  .strict();
+
+const ContentSetEventSchema = EventBaseSchema.extend({
+  type: z.literal('content.set'),
+  path: z.string().min(1),
+  value: z.unknown(),
+}).strict();
+
+const ListSetEventSchema = EventBaseSchema.extend({
+  type: z.literal('content.list.set'),
+  path: z.string().min(1),
+  value: z.array(z.unknown()),
+}).strict();
+
+const BlockAddEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.add'),
+  pageId: PageIdSchema,
+  block: BlockInstanceSchema,
+  index: z.number().int().nonnegative().optional(),
+}).strict();
+
+const BlockDuplicateEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.duplicate'),
+  pageId: PageIdSchema,
+  sourceBlockId: z.string().min(1),
+  block: BlockInstanceSchema,
+}).strict();
+
+const BlockRemoveEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.remove'),
+  pageId: PageIdSchema,
+  blockId: z.string().min(1),
+}).strict();
+
+const BlockReorderEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.reorder'),
+  pageId: PageIdSchema,
+  blockIds: z.array(z.string().min(1)).min(1),
+}).strict();
+
+const BlockVisibilityEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.visibility.set'),
+  pageId: PageIdSchema,
+  blockId: z.string().min(1),
+  visible: z.boolean(),
+}).strict();
+
+const BlockVariantEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.variant.set'),
+  pageId: PageIdSchema,
+  blockId: z.string().min(1),
+  variant: z.string().min(1),
+}).strict();
+
+const BlockSettingsEventSchema = EventBaseSchema.extend({
+  type: z.literal('block.settings.set'),
+  pageId: PageIdSchema,
+  blockId: z.string().min(1),
+  path: z.string().min(1),
+  value: z.unknown(),
+}).strict();
+
+const StyleSlotSetEventSchema = EventBaseSchema.extend({
+  type: z.literal('style.slot.set'),
+  slotId: StyleSlotIdSchema,
+  value: z.unknown(),
+  blockId: z.string().min(1).optional(),
+  breakpoint: z.enum(['base', 'sm', 'md', 'lg', 'xl']).optional(),
+}).strict();
+
+const StyleSlotResetEventSchema = EventBaseSchema.extend({
+  type: z.literal('style.slot.reset'),
+  slotId: StyleSlotIdSchema,
+  blockId: z.string().min(1).optional(),
+  breakpoint: z.enum(['base', 'sm', 'md', 'lg', 'xl']).optional(),
+}).strict();
+
+const PageUpsertEventSchema = EventBaseSchema.extend({
+  type: z.literal('page.upsert'),
+  page: CustomPageSchema,
+}).strict();
+
+const PageRemoveEventSchema = EventBaseSchema.extend({
+  type: z.literal('page.remove'),
+  pageId: PageIdSchema,
+}).strict();
+
+const TermsSetEventSchema = EventBaseSchema.extend({
+  type: z.literal('terms.set'),
+  key: z.enum(['termsOfService', 'privacyPolicy', 'refundPolicy', 'imprint']),
+  value: z.string(),
+}).strict();
+
+export const BuilderEventSchema = z.discriminatedUnion('type', [
+  ContentSetEventSchema,
+  ListSetEventSchema,
+  BlockAddEventSchema,
+  BlockDuplicateEventSchema,
+  BlockRemoveEventSchema,
+  BlockReorderEventSchema,
+  BlockVisibilityEventSchema,
+  BlockVariantEventSchema,
+  BlockSettingsEventSchema,
+  StyleSlotSetEventSchema,
+  StyleSlotResetEventSchema,
+  PageUpsertEventSchema,
+  PageRemoveEventSchema,
+  TermsSetEventSchema,
+]);
+export type BuilderEvent = z.infer<typeof BuilderEventSchema>;