@contentful/experience-design-system-types 2.2.1

package/README.md

@@ -0,0 +1,25 @@
+# @contentful/experience-design-system-types
+
+Shared TypeScript types for the Contentful Experience Design System import pipeline. Covers the two file formats consumers provide (CDF for components, DTCG for tokens) and the contract types for the Design System Sources API.
+
+## Modules
+
+### CDF — Component Definition Format
+
+Types and validation for `.cdf.json` component definition files that describe a design system's component library. Exports `validateCDF`, `CDF_V1_SCHEMA_URL`, `CDF_PROPERTY_TYPES`, `CDFComponentEntry`, `CDFPropertyDefinition`, `CDFValidationError`.
+
+### DTCG — Design Token Community Group
+
+Types for `.tokens.json` files in the [W3C DTCG format](https://tr.designtokens.org/format/) that describe a design system's token library. Exports `DESIGN_TOKEN_TYPES`, `DesignTokenType`, `DTCGTokenEntry`, `DTCGTokenGroup`, `DTCGTokenNode`, `DTCGTokenGroupNode`.
+
+### Sources API — Manifest
+
+Request body sent to both the preview and apply endpoints. Exports `ManifestPayload`.
+
+### Sources API — Preview
+
+Response types for the Sources API preview endpoint, which returns a diff of what will change before committing. Exports `ServerPreviewResponse`, `EntityDiffGroup`, `ChangedEntity`, `BreakingChange`, `ChangeClassification`, `DownstreamImpact`, and entity summary types (`ComponentTypeSummary`, `DesignTokenSummary`, `TaxonomySummary`, `PropertySummary`).
+
+### Sources API — Apply
+
+Response types for the Sources API apply endpoint, which runs the async import operation. Exports `ApplyOperationResponse`, `ApplyOperationItem`, `ApplyOperationItemError`, `ApplyOperationStatus`, `ApplyGateError`.

package/dist/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@contentful/experience-design-system-types",
+  "version": "2.2.1",
+  "type": "module",
+  "module": "./dist/src/index.js",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "nx build experience-design-system-types",
+    "typecheck": "nx typecheck experience-design-system-types",
+    "clean": "nx clean experience-design-system-types",
+    "test": "nx test experience-design-system-types",
+    "test:watch": "nx test:watch experience-design-system-types",
+    "lint": "nx lint experience-design-system-types",
+    "lint:fix": "nx lint:fix experience-design-system-types"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.3",
+    "@types/node": "^24.0.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vitest": "^4.0.16"
+  }
+}

package/dist/src/cdf/index.d.ts

@@ -0,0 +1,4 @@
+export { validateCDF, parseCDFComponents } from './validate.js';
+export { CDF_V1_SCHEMA_URL } from './schema.js';
+export { CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES } from './vocabularies.js';
+export type { CDFComponentEntry, CDFPropertyDefinition, CDFSlotDefinition, CDFValidationError } from './types.js';

package/dist/src/cdf/index.js

@@ -0,0 +1,3 @@
+export { validateCDF, parseCDFComponents } from './validate.js';
+export { CDF_V1_SCHEMA_URL } from './schema.js';
+export { CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES } from './vocabularies.js';

package/dist/src/cdf/schema.d.ts

@@ -0,0 +1,112 @@
+export declare const CDF_V1_SCHEMA_URL = "https://contentful.com/schemas/cdf/v1";
+export declare const cdfV1JsonSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://contentful.com/schemas/cdf/v1";
+    readonly title: "CDF Component Definition Format v1";
+    readonly type: "object";
+    readonly required: readonly ["$schema"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly const: "https://contentful.com/schemas/cdf/v1";
+        };
+    };
+    readonly additionalProperties: {
+        readonly $ref: "#/definitions/groupOrComponent";
+    };
+    readonly definitions: {
+        readonly groupOrComponent: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/definitions/component";
+            }, {
+                readonly $ref: "#/definitions/group";
+            }];
+        };
+        readonly component: {
+            readonly type: "object";
+            readonly required: readonly ["$type", "$properties"];
+            readonly properties: {
+                readonly $type: {
+                    readonly type: "string";
+                    readonly const: "component";
+                };
+                readonly $description: {
+                    readonly type: "string";
+                };
+                readonly $properties: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/definitions/property";
+                    };
+                };
+                readonly $slots: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/definitions/slot";
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly property: {
+            readonly type: "object";
+            readonly required: readonly ["$type", "$category"];
+            readonly properties: {
+                readonly $type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["string", "richtext", "media", "link", "enum", "token", "boolean"];
+                };
+                readonly $category: {
+                    readonly type: "string";
+                    readonly enum: readonly ["content", "design", "state"];
+                };
+                readonly $description: {
+                    readonly type: "string";
+                };
+                readonly $required: {
+                    readonly type: "boolean";
+                };
+                readonly $default: {};
+                readonly $values: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly '$token.kind': {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly slot: {
+            readonly type: "object";
+            readonly properties: {
+                readonly $description: {
+                    readonly type: "string";
+                };
+                readonly $required: {
+                    readonly type: "boolean";
+                };
+                readonly $allowedComponents: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly group: {
+            readonly type: "object";
+            readonly properties: {
+                readonly $description: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: {
+                readonly $ref: "#/definitions/groupOrComponent";
+            };
+        };
+    };
+};

package/dist/src/cdf/schema.js

@@ -0,0 +1,63 @@
+import { CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES } from './vocabularies.js';
+export const CDF_V1_SCHEMA_URL = 'https://contentful.com/schemas/cdf/v1';
+export const cdfV1JsonSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: CDF_V1_SCHEMA_URL,
+    title: 'CDF Component Definition Format v1',
+    type: 'object',
+    required: ['$schema'],
+    properties: {
+        $schema: { type: 'string', const: CDF_V1_SCHEMA_URL },
+    },
+    additionalProperties: { $ref: '#/definitions/groupOrComponent' },
+    definitions: {
+        groupOrComponent: {
+            oneOf: [{ $ref: '#/definitions/component' }, { $ref: '#/definitions/group' }],
+        },
+        component: {
+            type: 'object',
+            required: ['$type', '$properties'],
+            properties: {
+                $type: { type: 'string', const: 'component' },
+                $description: { type: 'string' },
+                $properties: {
+                    type: 'object',
+                    additionalProperties: { $ref: '#/definitions/property' },
+                },
+                $slots: {
+                    type: 'object',
+                    additionalProperties: { $ref: '#/definitions/slot' },
+                },
+            },
+            additionalProperties: false,
+        },
+        property: {
+            type: 'object',
+            required: ['$type', '$category'],
+            properties: {
+                $type: { type: 'string', enum: [...CDF_PROPERTY_TYPES] },
+                $category: { type: 'string', enum: [...CDF_PROPERTY_CATEGORIES] },
+                $description: { type: 'string' },
+                $required: { type: 'boolean' },
+                $default: {},
+                $values: { type: 'array', items: { type: 'string' } },
+                '$token.kind': { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        slot: {
+            type: 'object',
+            properties: {
+                $description: { type: 'string' },
+                $required: { type: 'boolean' },
+                $allowedComponents: { type: 'array', items: { type: 'string' } },
+            },
+            additionalProperties: false,
+        },
+        group: {
+            type: 'object',
+            properties: { $description: { type: 'string' } },
+            additionalProperties: { $ref: '#/definitions/groupOrComponent' },
+        },
+    },
+};

package/dist/src/cdf/types.d.ts

@@ -0,0 +1,44 @@
+import type { CDFPropertyType, CDFPropertyCategory } from './vocabularies.js';
+export interface CDFPropertyDefinition {
+    $type: CDFPropertyType;
+    $category: CDFPropertyCategory;
+    $description?: string;
+    $required?: boolean;
+    $default?: unknown;
+    $values?: string[];
+    '$token.kind'?: string;
+}
+export interface CDFSlotDefinition {
+    $description?: string;
+    $allowedComponents?: string[];
+    $required?: boolean;
+}
+export interface CDFComponentEntry {
+    $type: 'component';
+    $description?: string;
+    $properties: Record<string, CDFPropertyDefinition>;
+    $slots?: Record<string, CDFSlotDefinition>;
+}
+export type CDFGroupOrComponent = CDFComponentEntry | CDFGroup;
+export interface CDFGroup {
+    $description?: string;
+    [key: string]: CDFGroupOrComponent | string | undefined;
+}
+export interface CDFFile {
+    $schema: string;
+    [key: string]: CDFGroupOrComponent | string | undefined;
+}
+export interface CDFValidationError {
+    path: string;
+    message: string;
+    expected?: string;
+    actual?: string;
+}
+export interface CDFValidationResult {
+    valid: boolean;
+    errors: CDFValidationError[];
+    components: Array<{
+        key: string;
+        entry: CDFComponentEntry;
+    }>;
+}

package/dist/src/cdf/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/cdf/validate.d.ts

@@ -0,0 +1,6 @@
+import type { CDFComponentEntry, CDFValidationResult } from './types.js';
+export declare function parseCDFComponents(obj: Record<string, unknown>, prefix?: string): Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>;
+export declare function validateCDF(input: unknown): CDFValidationResult;

package/dist/src/cdf/validate.js

@@ -0,0 +1,52 @@
+import { Ajv } from 'ajv';
+import { cdfV1JsonSchema, CDF_V1_SCHEMA_URL } from './schema.js';
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile(cdfV1JsonSchema);
+function isComponentEntry(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '$type' in value &&
+        value['$type'] === 'component');
+}
+export function parseCDFComponents(obj, prefix = '') {
+    const results = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith('$'))
+            continue;
+        if (isComponentEntry(value)) {
+            results.push({ key: prefix ? `${prefix}.${key}` : key, entry: value });
+        }
+        else if (typeof value === 'object' && value !== null) {
+            results.push(...parseCDFComponents(value, prefix ? `${prefix}.${key}` : key));
+        }
+    }
+    return results;
+}
+export function validateCDF(input) {
+    const valid = validate(input);
+    if (!valid) {
+        const errors = (validate.errors ?? []).map((err) => ({
+            path: err.instancePath || '/',
+            message: err.message ?? 'Unknown validation error',
+            expected: err.params ? JSON.stringify(err.params) : undefined,
+        }));
+        return { valid: false, errors, components: [] };
+    }
+    const file = input;
+    if (file.$schema !== CDF_V1_SCHEMA_URL) {
+        return {
+            valid: false,
+            errors: [
+                {
+                    path: '/$schema',
+                    message: `Expected schema "${CDF_V1_SCHEMA_URL}"`,
+                    expected: CDF_V1_SCHEMA_URL,
+                    actual: file.$schema,
+                },
+            ],
+            components: [],
+        };
+    }
+    const components = parseCDFComponents(file);
+    return { valid: true, errors: [], components };
+}

package/dist/src/cdf/vocabularies.d.ts

@@ -0,0 +1,4 @@
+export declare const CDF_PROPERTY_TYPES: readonly ["string", "richtext", "media", "link", "enum", "token", "boolean"];
+export type CDFPropertyType = (typeof CDF_PROPERTY_TYPES)[number];
+export declare const CDF_PROPERTY_CATEGORIES: readonly ["content", "design", "state"];
+export type CDFPropertyCategory = (typeof CDF_PROPERTY_CATEGORIES)[number];

package/dist/src/cdf/vocabularies.js

@@ -0,0 +1,2 @@
+export const CDF_PROPERTY_TYPES = ['string', 'richtext', 'media', 'link', 'enum', 'token', 'boolean'];
+export const CDF_PROPERTY_CATEGORIES = ['content', 'design', 'state'];

package/dist/src/dtcg/index.d.ts

@@ -0,0 +1,4 @@
+export { DESIGN_TOKEN_TYPES, type DesignTokenType } from './token-types.js';
+export type { DTCGTokenEntry, DTCGTokenGroup, DTCGTokenNode, DTCGTokenGroupNode } from './types.js';
+export { flattenDTCG } from './utils.js';
+export { validateDTCG, type DTCGValidationError, type DTCGValidationResult } from './validate.js';

package/dist/src/dtcg/index.js

@@ -0,0 +1,3 @@
+export { DESIGN_TOKEN_TYPES } from './token-types.js';
+export { flattenDTCG } from './utils.js';
+export { validateDTCG } from './validate.js';

package/dist/src/dtcg/token-types.d.ts

@@ -0,0 +1,2 @@
+export declare const DESIGN_TOKEN_TYPES: readonly ["color", "dimension", "fontFamily", "fontWeight", "duration", "cubicBezier", "number", "strokeStyle", "border", "transition", "shadow", "gradient", "typography"];
+export type DesignTokenType = (typeof DESIGN_TOKEN_TYPES)[number];

package/dist/src/dtcg/token-types.js

@@ -0,0 +1,15 @@
+export const DESIGN_TOKEN_TYPES = [
+    'color',
+    'dimension',
+    'fontFamily',
+    'fontWeight',
+    'duration',
+    'cubicBezier',
+    'number',
+    'strokeStyle',
+    'border',
+    'transition',
+    'shadow',
+    'gradient',
+    'typography',
+];

package/dist/src/dtcg/types.d.ts

@@ -0,0 +1,22 @@
+import type { DesignTokenType } from './token-types.js';
+export interface DTCGTokenEntry {
+    path: string;
+    $type: DesignTokenType;
+    $value: unknown;
+    $description?: string;
+}
+export interface DTCGTokenGroup {
+    path: string;
+    $description?: string;
+    tokenIds: string[];
+}
+export type DTCGTokenNode = DTCGTokenLeaf | DTCGTokenGroupNode;
+export interface DTCGTokenLeaf {
+    $type: string;
+    $value: unknown;
+    $description?: string;
+}
+export interface DTCGTokenGroupNode {
+    $description?: string;
+    [key: string]: DTCGTokenNode | string | undefined;
+}

package/dist/src/dtcg/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/dtcg/utils.d.ts

@@ -0,0 +1,2 @@
+import type { DTCGTokenEntry } from './types.js';
+export declare function flattenDTCG(obj: Record<string, unknown>, prefix: string): DTCGTokenEntry[];

package/dist/src/dtcg/utils.js

@@ -0,0 +1,23 @@
+export function flattenDTCG(obj, prefix) {
+    const results = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith('$'))
+            continue;
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            continue;
+        const node = value;
+        const path = prefix ? `${prefix}.${key}` : key;
+        if ('$value' in node) {
+            results.push({
+                path,
+                $type: node.$type,
+                $value: node.$value,
+                $description: node.$description,
+            });
+        }
+        else {
+            results.push(...flattenDTCG(node, path));
+        }
+    }
+    return results;
+}

package/dist/src/dtcg/validate.d.ts

@@ -0,0 +1,10 @@
+export interface DTCGValidationError {
+    path: string;
+    message: string;
+    actual?: unknown;
+}
+export interface DTCGValidationResult {
+    valid: boolean;
+    errors: DTCGValidationError[];
+}
+export declare function validateDTCG(obj: Record<string, unknown>): DTCGValidationResult;

package/dist/src/dtcg/validate.js

@@ -0,0 +1,20 @@
+import { DESIGN_TOKEN_TYPES } from './token-types.js';
+import { flattenDTCG } from './utils.js';
+const TOKEN_TYPE_SET = new Set(DESIGN_TOKEN_TYPES);
+function isDesignTokenType(value) {
+    return typeof value === 'string' && TOKEN_TYPE_SET.has(value);
+}
+export function validateDTCG(obj) {
+    const errors = [];
+    const tokens = flattenDTCG(obj, '');
+    for (const token of tokens) {
+        if (!isDesignTokenType(token.$type)) {
+            errors.push({
+                path: token.path,
+                message: `Unknown $type "${token.$type}". Must be one of: ${DESIGN_TOKEN_TYPES.join(', ')}.`,
+                actual: token.$type,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { validateCDF, parseCDFComponents, CDF_V1_SCHEMA_URL, CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES, type CDFComponentEntry, type CDFPropertyDefinition, type CDFSlotDefinition, type CDFValidationError, } from './cdf/index.js';
+export { DESIGN_TOKEN_TYPES, flattenDTCG, validateDTCG, type DesignTokenType, type DTCGTokenEntry, type DTCGTokenGroup, type DTCGTokenNode, type DTCGTokenGroupNode, type DTCGValidationError, type DTCGValidationResult, } from './dtcg/index.js';
+export type { BreakingChange, ChangeClassification, DownstreamImpact, PropertySummary, ComponentTypeSummary, DesignTokenSummary, TaxonomySummary, ChangedEntity, EntityDiffGroup, ServerPreviewResponse, } from './sources-api/preview/index.js';
+export type { ApplyOperationStatus, ApplyOperationItemError, ApplyOperationItem, ApplyOperationResponse, ApplyGateError, } from './sources-api/apply/index.js';
+export type { ManifestPayload } from './sources-api/manifest/index.js';
+export { buildManifest, buildFilteredManifest, stripUnsupportedSlotFields } from './sources-api/manifest/index.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+// CDF (Component Definition Format)
+export { validateCDF, parseCDFComponents, CDF_V1_SCHEMA_URL, CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES, } from './cdf/index.js';
+// DTCG (W3C Design Token Community Group)
+export { DESIGN_TOKEN_TYPES, flattenDTCG, validateDTCG, } from './dtcg/index.js';
+export { buildManifest, buildFilteredManifest, stripUnsupportedSlotFields } from './sources-api/manifest/index.js';

package/dist/src/sources-api/apply/index.d.ts

@@ -0,0 +1,49 @@
+export type ApplyOperationStatus = 'queued' | 'running' | 'succeeded' | 'partial' | 'failed';
+export interface ApplyOperationItemError {
+    code: string;
+    message: string;
+}
+export interface ApplyOperationItem {
+    entityType: 'ComponentType' | 'DesignToken';
+    id: string;
+    action: 'create' | 'update' | 'delete';
+    status: 'queued' | 'succeeded' | 'failed';
+    error?: string | ApplyOperationItemError;
+}
+export interface ApplyOperationResponse {
+    sys: {
+        type: 'ApplyOperation';
+        id: string;
+        status: ApplyOperationStatus;
+        createdAt: string;
+        createdBy: {
+            sys: {
+                type: 'Link';
+                linkType: string;
+                id: string;
+            };
+        };
+    };
+    summary: {
+        total: number;
+        pending: number;
+        succeeded: number;
+        failed: number;
+    };
+    items?: ApplyOperationItem[];
+}
+export interface ApplyGateError {
+    sys: {
+        type: 'Error';
+        id: string;
+    };
+    message: string;
+    details?: {
+        breakingComponentIds?: string[];
+        affectedEntities?: number;
+        errors?: Array<{
+            path: string;
+            message: string;
+        }>;
+    };
+}

package/dist/src/sources-api/apply/index.js

@@ -0,0 +1 @@
+export {};

package/dist/src/sources-api/manifest/index.d.ts

@@ -0,0 +1,5 @@
+export interface ManifestPayload {
+    componentsManifest?: Record<string, unknown>;
+    tokensManifest?: Record<string, unknown>;
+}
+export { buildManifest, buildFilteredManifest, stripUnsupportedSlotFields } from './utils.js';

package/dist/src/sources-api/manifest/index.js

@@ -0,0 +1 @@
+export { buildManifest, buildFilteredManifest, stripUnsupportedSlotFields } from './utils.js';

package/dist/src/sources-api/manifest/utils.d.ts

@@ -0,0 +1,9 @@
+import type { CDFComponentEntry } from '../../cdf/index.js';
+import type { DTCGTokenEntry } from '../../dtcg/types.js';
+import type { ManifestPayload } from './index.js';
+export declare function stripUnsupportedSlotFields(entry: CDFComponentEntry): CDFComponentEntry;
+export declare function buildManifest(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>, tokens: DTCGTokenEntry[]): ManifestPayload;
+export declare function buildFilteredManifest(fullManifest: ManifestPayload, selectedComponentKeys: Set<string>, selectedTokenPaths: Set<string>): ManifestPayload;

package/dist/src/sources-api/manifest/utils.js

@@ -0,0 +1,60 @@
+import { CDF_V1_SCHEMA_URL } from '../../cdf/index.js';
+export function stripUnsupportedSlotFields(entry) {
+    if (!entry.$slots)
+        return entry;
+    const cleaned = {};
+    for (const [name, slot] of Object.entries(entry.$slots)) {
+        const { $required: _required, ...rest } = slot;
+        cleaned[name] = rest;
+    }
+    return { ...entry, $slots: cleaned };
+}
+export function buildManifest(components, tokens) {
+    const manifest = {};
+    if (components.length > 0) {
+        const componentsObj = { $schema: CDF_V1_SCHEMA_URL };
+        for (const { key, entry } of components) {
+            componentsObj[key] = stripUnsupportedSlotFields(entry);
+        }
+        manifest.componentsManifest = componentsObj;
+    }
+    if (tokens.length > 0) {
+        const tokensObj = {};
+        for (const token of tokens) {
+            tokensObj[token.path] = {
+                $type: token.$type,
+                $value: token.$value,
+                ...(token.$description ? { $description: token.$description } : {}),
+            };
+        }
+        manifest.tokensManifest = tokensObj;
+    }
+    return manifest;
+}
+export function buildFilteredManifest(fullManifest, selectedComponentKeys, selectedTokenPaths) {
+    const filtered = {};
+    if (fullManifest.componentsManifest) {
+        const obj = {};
+        if (fullManifest.componentsManifest['$schema']) {
+            obj['$schema'] = fullManifest.componentsManifest['$schema'];
+        }
+        for (const [key, value] of Object.entries(fullManifest.componentsManifest)) {
+            if (key === '$schema')
+                continue;
+            if (selectedComponentKeys.has(key))
+                obj[key] = value;
+        }
+        if (Object.keys(obj).length > 1)
+            filtered.componentsManifest = obj;
+    }
+    if (fullManifest.tokensManifest) {
+        const obj = {};
+        for (const [path, value] of Object.entries(fullManifest.tokensManifest)) {
+            if (selectedTokenPaths.has(path))
+                obj[path] = value;
+        }
+        if (Object.keys(obj).length > 0)
+            filtered.tokensManifest = obj;
+    }
+    return filtered;
+}

package/dist/src/sources-api/preview/index.d.ts

@@ -0,0 +1,54 @@
+export interface BreakingChange {
+    propertyId: string;
+    reason: 'removed' | 'added_required_no_default' | 'type_changed' | 'validation_narrowed';
+}
+export interface ChangeClassification {
+    classification: 'breaking' | 'compatible';
+    breakingChanges: BreakingChange[];
+}
+export interface DownstreamImpact {
+    affectedFragments: number;
+    affectedExperiences: number;
+}
+export interface PropertySummary {
+    type: string;
+    category: string;
+    required: boolean;
+    default?: unknown;
+}
+export interface ComponentTypeSummary {
+    id: string;
+    name: string;
+    contentProperties: string[];
+    designProperties: string[];
+    slots: string[];
+    fullProperties?: Record<string, PropertySummary>;
+}
+export interface DesignTokenSummary {
+    id: string;
+    name: string;
+    kind: string;
+}
+export interface TaxonomySummary {
+    id: string;
+    name: string;
+    tokenIds: string[];
+}
+export interface ChangedEntity<TCurrent, TProposed> {
+    current: TCurrent;
+    proposed: TProposed;
+    hasPendingDraftChanges: boolean;
+    changeClassification?: ChangeClassification;
+    impact?: DownstreamImpact;
+}
+export interface EntityDiffGroup<TCurrent, TProposed> {
+    new: TProposed[];
+    changed: ChangedEntity<TCurrent, TProposed>[];
+    unchanged: string[];
+    removed: TCurrent[];
+}
+export interface ServerPreviewResponse {
+    components: EntityDiffGroup<ComponentTypeSummary, Record<string, unknown>>;
+    tokens: EntityDiffGroup<DesignTokenSummary, Record<string, unknown>>;
+    taxonomies: EntityDiffGroup<TaxonomySummary, Record<string, unknown>>;
+}

package/dist/src/sources-api/preview/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@contentful/experience-design-system-types",
+  "version": "2.2.1",
+  "type": "module",
+  "module": "./dist/src/index.js",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.3",
+    "@types/node": "^24.0.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "nx build experience-design-system-types",
+    "typecheck": "nx typecheck experience-design-system-types",
+    "clean": "nx clean experience-design-system-types",
+    "test": "nx test experience-design-system-types",
+    "test:watch": "nx test:watch experience-design-system-types",
+    "lint": "nx lint experience-design-system-types",
+    "lint:fix": "nx lint:fix experience-design-system-types"
+  }
+}