@shoppexio/builder-contracts 0.1.0

package/dist/theme-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-manifest.d.ts","sourceRoot":"","sources":["../src/theme-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,eAAO,MAAM,aAAa,aAAoD,CAAC;AAC/E,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,kBAAkB;;;;kBAMpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,kBAAkB;;;;kBAMpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,kBAAkB;;;;;;;;;kBAOpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAWrB,CAAC;AACZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA+D5B,CAAC;AACL,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAEhE"}

package/dist/theme-manifest.js

@@ -0,0 +1,119 @@
+import * as z from 'zod/v4';
+import { BlockSettingsSchema } from "./fields.js";
+import { StyleSlotDefaultsSchema, StyleSlotIdSchema } from "./style-slots.js";
+export const ThemeIdSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_.]*$/);
+export const BlockVariantSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    previewImage: z.string().url().optional(),
+})
+    .strict();
+export const DefaultBlockSchema = z
+    .object({
+    type: z.string().min(1),
+    variant: z.string().min(1).optional(),
+    settings: z.record(z.string().min(1), z.unknown()).optional(),
+})
+    .strict();
+export const ManifestPageSchema = z
+    .object({
+    label: z.string().min(1),
+    previewPath: z.string().min(1).optional(),
+    allowedBlocks: z.array(z.string().min(1)).default([]),
+    defaultBlocks: z.array(DefaultBlockSchema).default([]),
+})
+    .strict();
+export const BlockPresetSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    variant: z.string().min(1).optional(),
+    settings: z.record(z.string().min(1), z.unknown()).default({}),
+    style_overrides: StyleSlotDefaultsSchema.optional(),
+})
+    .strict();
+export const ManifestBlockSchema = z
+    .object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    category: z.string().min(1).optional(),
+    maxInstances: z.number().int().positive().optional(),
+    variants: z.array(BlockVariantSchema).default([]),
+    settings: BlockSettingsSchema.default({}),
+    exposedStyleSlots: z.array(StyleSlotIdSchema).default([]),
+    presets: z.array(BlockPresetSchema).default([]),
+})
+    .strict();
+export const ThemePresetSchema = z
+    .object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    content: z.record(z.string().min(1), z.unknown()).default({}),
+    layout: z.record(z.string().min(1), z.unknown()).default({}),
+    style_slots: StyleSlotDefaultsSchema.default({}),
+})
+    .strict();
+export const ThemeManifestSchema = z
+    .object({
+    id: ThemeIdSchema,
+    name: z.string().min(1),
+    version: z.string().min(1),
+    pages: z.record(z.string().min(1), ManifestPageSchema),
+    blocks: z.record(z.string().min(1), ManifestBlockSchema),
+    styleSlots: StyleSlotDefaultsSchema.default({}),
+    presets: z.record(z.string().min(1), ThemePresetSchema).default({}),
+})
+    .strict()
+    .superRefine((manifest, ctx) => {
+    for (const [pageId, page] of Object.entries(manifest.pages)) {
+        for (const blockType of page.allowedBlocks) {
+            if (!manifest.blocks[blockType]) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['pages', pageId, 'allowedBlocks'],
+                    message: `Page "${pageId}" allows unknown block "${blockType}"`,
+                });
+            }
+        }
+        for (const [index, block] of page.defaultBlocks.entries()) {
+            if (!manifest.blocks[block.type]) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['pages', pageId, 'defaultBlocks', index, 'type'],
+                    message: `Page "${pageId}" defaults unknown block "${block.type}"`,
+                });
+                continue;
+            }
+            if (!page.allowedBlocks.includes(block.type)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['pages', pageId, 'defaultBlocks', index, 'type'],
+                    message: `Page "${pageId}" defaults block "${block.type}" without allowing it`,
+                });
+            }
+            const blockDefinition = manifest.blocks[block.type];
+            if (block.variant && !blockDefinition.variants.some((variant) => variant.id === block.variant)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['pages', pageId, 'defaultBlocks', index, 'variant'],
+                    message: `Block "${block.type}" does not expose variant "${block.variant}"`,
+                });
+            }
+        }
+    }
+    for (const [blockType, block] of Object.entries(manifest.blocks)) {
+        for (const preset of block.presets) {
+            if (preset.variant && !block.variants.some((variant) => variant.id === preset.variant)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['blocks', blockType, 'presets', preset.id, 'variant'],
+                    message: `Block preset "${preset.id}" references unknown variant "${preset.variant}"`,
+                });
+            }
+        }
+    }
+});
+export function parseThemeManifest(input) {
+    return ThemeManifestSchema.parse(input);
+}

package/dist/validation.d.ts

@@ -0,0 +1,16 @@
+import type { BuilderSettings } from './builder-settings.ts';
+import type { ThemeManifest } from './theme-manifest.ts';
+export type BuilderManifestValidationIssueCode = 'unknown_page' | 'duplicate_block_id' | 'unknown_block_type' | 'block_not_allowed' | 'too_many_block_instances' | 'unknown_block_variant' | 'unknown_block_setting' | 'unexposed_style_slot';
+export type BuilderManifestValidationIssue = {
+    code: BuilderManifestValidationIssueCode;
+    path: string;
+    message: string;
+};
+export declare class BuilderManifestValidationError extends Error {
+    readonly issues: BuilderManifestValidationIssue[];
+    constructor(issues: BuilderManifestValidationIssue[]);
+}
+export declare function validateBuilderSettingsAgainstManifest(settings: BuilderSettings, manifest: ThemeManifest): BuilderManifestValidationIssue[];
+export declare function assertBuilderSettingsMatchManifest(settings: BuilderSettings, manifest: ThemeManifest): void;
+export declare function formatBuilderManifestValidationIssues(issues: BuilderManifestValidationIssue[]): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,kCAAkC,GAC1C,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,0BAA0B,GAC1B,uBAAuB,GACvB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,kCAAkC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,MAAM,EAAE,8BAA8B,EAAE,CAAC;gBAEtC,MAAM,EAAE,8BAA8B,EAAE;CAKrD;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,8BAA8B,EAAE,CAkElC;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,IAAI,CAKN;AAED,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,8BAA8B,EAAE,GACvC,MAAM,CAQR"}

package/dist/validation.js

@@ -0,0 +1,131 @@
+export class BuilderManifestValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(formatBuilderManifestValidationIssues(issues));
+        this.name = 'BuilderManifestValidationError';
+        this.issues = issues;
+    }
+}
+export function validateBuilderSettingsAgainstManifest(settings, manifest) {
+    const issues = [];
+    for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
+        const page = manifest.pages[pageId];
+        if (!page) {
+            issues.push({
+                code: 'unknown_page',
+                path: `theme.layout.${pageId}`,
+                message: `Unknown builder page "${pageId}"`,
+            });
+            continue;
+        }
+        const blockIds = new Set();
+        const blockTypeCounts = new Map();
+        for (const [index, block] of layout.blocks.entries()) {
+            const blockPath = `theme.layout.${pageId}.blocks.${index}`;
+            if (blockIds.has(block.id)) {
+                issues.push({
+                    code: 'duplicate_block_id',
+                    path: `${blockPath}.id`,
+                    message: `Duplicate block id "${block.id}" on page "${pageId}"`,
+                });
+            }
+            blockIds.add(block.id);
+            const blockDefinition = manifest.blocks[block.type];
+            if (!blockDefinition) {
+                issues.push({
+                    code: 'unknown_block_type',
+                    path: `${blockPath}.type`,
+                    message: `Unknown builder block type "${block.type}"`,
+                });
+                continue;
+            }
+            if (!page.allowedBlocks.includes(block.type)) {
+                issues.push({
+                    code: 'block_not_allowed',
+                    path: `${blockPath}.type`,
+                    message: `Block "${block.type}" is not allowed on page "${pageId}"`,
+                });
+            }
+            blockTypeCounts.set(block.type, (blockTypeCounts.get(block.type) ?? 0) + 1);
+            validateBlockVariant(block, blockDefinition.variants, blockPath, issues);
+            validateBlockSettings(block, Object.keys(blockDefinition.settings), blockPath, issues);
+            validateBlockStyleOverrides(block, blockDefinition.exposedStyleSlots, blockPath, issues);
+        }
+        for (const [blockType, count] of blockTypeCounts.entries()) {
+            const maxInstances = manifest.blocks[blockType]?.maxInstances;
+            if (maxInstances !== undefined && count > maxInstances) {
+                issues.push({
+                    code: 'too_many_block_instances',
+                    path: `theme.layout.${pageId}.blocks`,
+                    message: `Page "${pageId}" has ${count} "${blockType}" blocks but the manifest allows ${maxInstances}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+export function assertBuilderSettingsMatchManifest(settings, manifest) {
+    const issues = validateBuilderSettingsAgainstManifest(settings, manifest);
+    if (issues.length > 0) {
+        throw new BuilderManifestValidationError(issues);
+    }
+}
+export function formatBuilderManifestValidationIssues(issues) {
+    if (issues.length === 0) {
+        return 'Builder settings match the theme manifest';
+    }
+    const [firstIssue] = issues;
+    const suffix = issues.length === 1 ? '' : ` (+${issues.length - 1} more)`;
+    return `${firstIssue.message}${suffix}`;
+}
+function validateBlockSettings(block, settingPaths, blockPath, issues) {
+    if (settingPaths.length === 0 && Object.keys(block.settings).length === 0) {
+        return;
+    }
+    const allowedSettings = new Set();
+    for (const path of settingPaths) {
+        allowedSettings.add(path);
+        allowedSettings.add(getShortSettingKey(path));
+    }
+    for (const key of Object.keys(block.settings)) {
+        if (allowedSettings.has(key)) {
+            continue;
+        }
+        issues.push({
+            code: 'unknown_block_setting',
+            path: `${blockPath}.settings.${key}`,
+            message: `Block "${block.id}" stores unknown setting "${key}"`,
+        });
+    }
+}
+function validateBlockVariant(block, variants, blockPath, issues) {
+    if (!block.variant) {
+        return;
+    }
+    if (!variants.some((variant) => variant.id === block.variant)) {
+        issues.push({
+            code: 'unknown_block_variant',
+            path: `${blockPath}.variant`,
+            message: `Block "${block.id}" uses unknown variant "${block.variant}"`,
+        });
+    }
+}
+function getShortSettingKey(path) {
+    const parts = path.split('.').filter(Boolean);
+    return parts.at(-1) ?? path;
+}
+function validateBlockStyleOverrides(block, exposedStyleSlots, blockPath, issues) {
+    if (!block.style_overrides) {
+        return;
+    }
+    const exposed = new Set(exposedStyleSlots);
+    for (const slotId of Object.keys(block.style_overrides)) {
+        if (!exposed.has(slotId)) {
+            issues.push({
+                code: 'unexposed_style_slot',
+                path: `${blockPath}.style_overrides.${slotId}`,
+                message: `Block "${block.id}" cannot override unexposed style slot "${slotId}"`,
+            });
+        }
+    }
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@shoppexio/builder-contracts",
+  "version": "0.1.0",
+  "description": "Shared Builder v2 contracts for Shoppex dashboard, backend, preview runtime, and themes",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShoppexIO/shoppex.git",
+    "directory": "packages/builder-contracts"
+  },
+  "homepage": "https://docs.shoppex.io",
+  "bugs": {
+    "url": "https://github.com/ShoppexIO/shoppex/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./builder-settings": {
+      "bun": "./src/builder-settings.ts",
+      "types": "./dist/builder-settings.d.ts",
+      "import": "./dist/builder-settings.js",
+      "default": "./dist/builder-settings.js"
+    },
+    "./events": {
+      "bun": "./src/events.ts",
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js",
+      "default": "./dist/events.js"
+    },
+    "./fields": {
+      "bun": "./src/fields.ts",
+      "types": "./dist/fields.d.ts",
+      "import": "./dist/fields.js",
+      "default": "./dist/fields.js"
+    },
+    "./legacy-manifest": {
+      "bun": "./src/legacy-manifest.ts",
+      "types": "./dist/legacy-manifest.d.ts",
+      "import": "./dist/legacy-manifest.js",
+      "default": "./dist/legacy-manifest.js"
+    },
+    "./migrations": {
+      "bun": "./src/migrations.ts",
+      "types": "./dist/migrations.d.ts",
+      "import": "./dist/migrations.js",
+      "default": "./dist/migrations.js"
+    },
+    "./preview-protocol": {
+      "bun": "./src/preview-protocol.ts",
+      "types": "./dist/preview-protocol.d.ts",
+      "import": "./dist/preview-protocol.js",
+      "default": "./dist/preview-protocol.js"
+    },
+    "./style-slots": {
+      "bun": "./src/style-slots.ts",
+      "types": "./dist/style-slots.d.ts",
+      "import": "./dist/style-slots.js",
+      "default": "./dist/style-slots.js"
+    },
+    "./theme-manifest": {
+      "bun": "./src/theme-manifest.ts",
+      "types": "./dist/theme-manifest.d.ts",
+      "import": "./dist/theme-manifest.js",
+      "default": "./dist/theme-manifest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src",
+    "clean": "rm -rf dist"
+  },
+  "author": "Shoppex",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
+}