@vieda/api-contract 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,653 @@
+import { type AssetEntry, type AssetManifest, type ComponentDoc, type TokensDoc, type ViedaConfig } from '@vieda/ir';
+import { z } from 'zod';
+/**
+ * Maximum size of a single uploaded asset. Kept safely under Vercel's ~4.5MB
+ * serverless request/response body limit, since asset bytes flow through the
+ * cloud function in both directions. Enforced by the cloud upload route, the
+ * local editor server, and a `vd publish` pre-check so all three agree.
+ */
+export declare const MAX_ASSET_BYTES: number;
+/** An empty manifest — the "no assets" state, used as a parse/consumer default. */
+export declare const EMPTY_ASSET_MANIFEST: AssetManifest;
+/** MIME type by extension, for uploads that arrive without a content type. */
+export declare const CONTENT_TYPE_BY_EXT: Record<string, string>;
+/**
+ * Bare, lowercased file extension, or null when there isn't a usable one.
+ * Shared so the local and cloud upload handlers derive it identically.
+ */
+export declare function assetExtOf(filename: string): string | null;
+/** Stored content type: the provided one, else inferred from the extension. */
+export declare function assetContentType(ext: string, provided?: string): string;
+/**
+ * Deterministic JSON serialization: independent of object key order and (via
+ * codepoint key sorting, not localeCompare) of the machine's locale. Both
+ * sync-state checks build on it — the CLI hashes it into design/version.json,
+ * and the cloud compares Draft vs latest Version canonical strings directly.
+ * Array order is preserved: it's meaningful in documents (children).
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Sync state of the editable design source against published Versions, as
+ * reported by GET /api/backend. Local backend: design/ vs design/version.json.
+ * Cloud backend: the Draft vs the latest published Version. Matches the
+ * compiler's `CompileProvenance` shape so the CLI can reuse it directly.
+ */
+export interface DesignVersionState {
+    number: number;
+    label: string | null;
+    publishedAt: string;
+    /** True when the editable source has drifted from the published Version. */
+    modified: boolean;
+}
+/** What GET /api/project returns from both the local and cloud backends. */
+export interface ProjectPayload {
+    config: ViedaConfig;
+    components: ComponentDoc[];
+    tokens: TokensDoc;
+    assets: AssetManifest;
+}
+/**
+ * What GET /api/backend returns. The editor probes this once to decide which
+ * shell to render and which actions (generate/publish/pull) to expose.
+ */
+export interface BackendInfo {
+    mode: 'local' | 'cloud';
+    capabilities: {
+        generate: boolean;
+        publish: boolean;
+        pull: boolean;
+        /** Whether this backend accepts asset uploads (POST .../assets). */
+        upload: boolean;
+        /**
+         * Whether this backend can scan the project's source code for component
+         * references (GET .../components/:name/code-usage). Local only — the
+         * cloud stores design documents, never the repo.
+         */
+        codeUsage: boolean;
+    };
+    user?: {
+        email: string;
+        name?: string;
+    };
+    project?: {
+        id: string;
+        name: string;
+    };
+    /**
+     * Which published Version the editable design source corresponds to, and
+     * whether it has been modified since. Absent when the project has never
+     * been pulled/published (local) or has no published Versions (cloud).
+     */
+    designVersion?: DesignVersionState;
+}
+/** Immutable metadata for one published Version. */
+export interface VersionMeta {
+    id: string;
+    number: number;
+    label: string | null;
+    createdAt: string;
+    createdBy: {
+        email: string;
+        name?: string;
+    };
+    basedOnVersionId: string | null;
+}
+/** A full Version: metadata plus the whole-project document snapshot. */
+export interface VersionSnapshot {
+    meta: VersionMeta;
+    components: ComponentDoc[];
+    tokens: TokensDoc;
+    assets: AssetManifest;
+}
+export declare const versionMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    number: z.ZodNumber;
+    label: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    createdBy: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        name?: string | undefined;
+    }, {
+        email: string;
+        name?: string | undefined;
+    }>;
+    basedOnVersionId: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    number: number;
+    id: string;
+    label: string | null;
+    createdAt: string;
+    createdBy: {
+        email: string;
+        name?: string | undefined;
+    };
+    basedOnVersionId: string | null;
+}, {
+    number: number;
+    id: string;
+    label: string | null;
+    createdAt: string;
+    createdBy: {
+        email: string;
+        name?: string | undefined;
+    };
+    basedOnVersionId: string | null;
+}>;
+/**
+ * Contents of `design/version.json` — written by `vd pull` and `vd publish`
+ * to record which published Version the local design files correspond to.
+ * `digest` is the CLI's canonical sha256 over the whole snapshot (components
+ * + tokens + assets manifest); `vd generate` recomputes it against the local
+ * files to detect modifications since the pull/publish and stamps generated
+ * headers accordingly.
+ */
+export declare const designVersionFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    version: z.ZodObject<{
+        id: z.ZodString;
+        number: z.ZodNumber;
+        label: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        createdBy: z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            email: string;
+            name?: string | undefined;
+        }, {
+            email: string;
+            name?: string | undefined;
+        }>;
+        basedOnVersionId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    }, {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    }>;
+    digest: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    version: {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    };
+    digest: string;
+}, {
+    schemaVersion: 1;
+    version: {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    };
+    digest: string;
+}>;
+export type DesignVersionFile = z.infer<typeof designVersionFileSchema>;
+/**
+ * Validates a pulled snapshot with the exact document schemas the compiler
+ * uses locally, so a bad payload fails loudly before touching design files.
+ */
+export declare const versionSnapshotSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        id: z.ZodString;
+        number: z.ZodNumber;
+        label: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        createdBy: z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            email: string;
+            name?: string | undefined;
+        }, {
+            email: string;
+            name?: string | undefined;
+        }>;
+        basedOnVersionId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    }, {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    }>;
+    components: z.ZodArray<z.ZodType<ComponentDoc, z.ZodTypeDef, ComponentDoc>, "many">;
+    tokens: z.ZodObject<{
+        schemaVersion: z.ZodNumber;
+        colors: z.ZodRecord<z.ZodString, z.ZodString>;
+        spacing: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        radii: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        textStyles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            fontFamily: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                token: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                token: string;
+            }, {
+                token: string;
+            }>]>>;
+            fontSize: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodType<import("@vieda/ir").UnitValue, z.ZodTypeDef, import("@vieda/ir").UnitValue>]>>;
+            fontWeight: z.ZodOptional<z.ZodNumber>;
+            fontStyle: z.ZodOptional<z.ZodEnum<["normal", "italic"]>>;
+            lineHeight: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodType<import("@vieda/ir").UnitValue, z.ZodTypeDef, import("@vieda/ir").UnitValue>]>>;
+            letterSpacing: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodType<import("@vieda/ir").UnitValue, z.ZodTypeDef, import("@vieda/ir").UnitValue>]>>;
+            color: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                token: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                token: string;
+            }, {
+                token: string;
+            }>]>>;
+            textAlign: z.ZodOptional<z.ZodEnum<["left", "center", "right"]>>;
+            decoration: z.ZodOptional<z.ZodEnum<["underline", "strikethrough"]>>;
+            textCase: z.ZodOptional<z.ZodEnum<["uppercase", "lowercase", "capitalize"]>>;
+        }, "strip", z.ZodTypeAny, {
+            color
+            /** Recursively sort object keys (arrays keep their order). */
+            ?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }, {
+            color?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }>>>;
+        fonts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            family: z.ZodString;
+            url: z.ZodString;
+            weights: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+            fallback: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }>>>;
+        breakpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        resetDefaultStyles: z.ZodOptional<z.ZodBoolean>;
+        settings: z.ZodOptional<z.ZodObject<{
+            allowedUnits: z.ZodOptional<z.ZodArray<z.ZodEnum<["rem", "em", "%"]>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        }, {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        schemaVersion: number;
+        breakpoints: Record<string, number>;
+        colors: Record<string, string>;
+        spacing: Record<string, number>;
+        radii: Record<string, number>;
+        textStyles: Record<string, {
+            color?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }>;
+        fonts: Record<string, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }>;
+        resetDefaultStyles?: boolean | undefined;
+        settings?: {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        } | undefined;
+    }, {
+        schemaVersion: number;
+        colors: Record<string, string>;
+        spacing: Record<string, number>;
+        radii: Record<string, number>;
+        breakpoints?: Record<string, number> | undefined;
+        textStyles?: Record<string, {
+            color?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }> | undefined;
+        fonts?: Record<string, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }> | undefined;
+        resetDefaultStyles?: boolean | undefined;
+        settings?: {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        } | undefined;
+    }>;
+    assets: z.ZodDefault<z.ZodObject<{
+        schemaVersion: z.ZodNumber;
+        assets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            digest: z.ZodString;
+            contentType: z.ZodString;
+            ext: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }, {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        assets: {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }[];
+        schemaVersion: number;
+    }, {
+        schemaVersion: number;
+        assets?: {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    meta: {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    };
+    components: ComponentDoc[];
+    tokens: {
+        schemaVersion: number;
+        breakpoints: Record<string, number>;
+        colors: Record<string, string>;
+        spacing: Record<string, number>;
+        radii: Record<string, number>;
+        textStyles: Record<string, {
+            color?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }>;
+        fonts: Record<string, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }>;
+        resetDefaultStyles?: boolean | undefined;
+        settings?: {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        } | undefined;
+    };
+    assets: {
+        assets: {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }[];
+        schemaVersion: number;
+    };
+}, {
+    meta: {
+        number: number;
+        id: string;
+        label: string | null;
+        createdAt: string;
+        createdBy: {
+            email: string;
+            name?: string | undefined;
+        };
+        basedOnVersionId: string | null;
+    };
+    components: ComponentDoc[];
+    tokens: {
+        schemaVersion: number;
+        colors: Record<string, string>;
+        spacing: Record<string, number>;
+        radii: Record<string, number>;
+        breakpoints?: Record<string, number> | undefined;
+        textStyles?: Record<string, {
+            color?: string | {
+                token: string;
+            } | undefined;
+            fontFamily?: string | {
+                token: string;
+            } | undefined;
+            fontSize?: number | import("@vieda/ir").UnitValue | undefined;
+            fontWeight?: number | undefined;
+            fontStyle?: "normal" | "italic" | undefined;
+            lineHeight?: number | import("@vieda/ir").UnitValue | undefined;
+            letterSpacing?: number | import("@vieda/ir").UnitValue | undefined;
+            textAlign?: "left" | "center" | "right" | undefined;
+            decoration?: "underline" | "strikethrough" | undefined;
+            textCase?: "uppercase" | "lowercase" | "capitalize" | undefined;
+        }> | undefined;
+        fonts?: Record<string, {
+            family: string;
+            url: string;
+            weights?: number[] | undefined;
+            fallback?: string | undefined;
+        }> | undefined;
+        resetDefaultStyles?: boolean | undefined;
+        settings?: {
+            allowedUnits?: ("rem" | "em" | "%")[] | undefined;
+        } | undefined;
+    };
+    assets?: {
+        schemaVersion: number;
+        assets?: {
+            name: string;
+            digest: string;
+            contentType: string;
+            ext: string;
+        }[] | undefined;
+    } | undefined;
+}>;
+/** One project as listed for the CLI and the cloud project picker. */
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    org: {
+        id: string;
+        name: string;
+    };
+}
+/** What a pull reports back: design files written and stale files removed. */
+export interface PullResult {
+    written: string[];
+    deleted: string[];
+    /** Asset files written into assetsDir. */
+    assetsWritten: string[];
+    /** Stale asset files removed from assetsDir. */
+    assetsDeleted: string[];
+    version: VersionMeta;
+}
+/**
+ * What POST .../assets returns: the manifest entry for the uploaded file. The
+ * server derives `digest` (sha256) and `ext` from the bytes and original name,
+ * deduping identical content, so repeated uploads are cheap.
+ */
+export type AssetUploadResult = AssetEntry;
+export declare const assetUploadResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    digest: z.ZodString;
+    contentType: z.ZodString;
+    ext: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    digest: string;
+    contentType: string;
+    ext: string;
+}, {
+    name: string;
+    digest: string;
+    contentType: string;
+    ext: string;
+}>;
+/**
+ * What PATCH .../assets/:name returns: the manifest entry under its new name.
+ * The request body is JSON `{ name: string }`. Both backends implement the
+ * same contract: `200` with the updated entry (digest unchanged — the bytes
+ * don't move); `400` if the new name fails the asset-name regex; `404` if
+ * `:name` isn't in the manifest; `409` if the new name is already taken.
+ */
+export type AssetRenameResult = AssetEntry;
+export declare const assetRenameResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    digest: z.ZodString;
+    contentType: z.ZodString;
+    ext: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    digest: string;
+    contentType: string;
+    ext: string;
+}, {
+    name: string;
+    digest: string;
+    contentType: string;
+    ext: string;
+}>;
+/**
+ * What GET .../components/:name/code-usage returns: places in the project's
+ * own (non-generated) source files that mention the component, so the editor
+ * can warn before a delete that hand-written code still imports or renders
+ * it. Best-effort text search — `404` if `:name` isn't a component. Local
+ * backend only; gated by the `codeUsage` capability.
+ */
+export interface CodeUsageResult {
+    matches: CodeUsageMatch[];
+    /** True when the scan stopped early because the match cap was hit. */
+    truncated: boolean;
+}
+export interface CodeUsageMatch {
+    /** Repo-relative POSIX path of the referencing file. */
+    file: string;
+    /** 1-based line number of the match. */
+    line: number;
+    /** The matching line, trimmed. */
+    text: string;
+}
+/**
+ * What PATCH .../components/:name returns: the renamed component document. The
+ * request body is JSON `{ name: string }` (the new PascalCase name). Both
+ * backends implement the same contract: `200` with the renamed doc (its
+ * internal `name`, and the root node's name when it still matched, updated to
+ * the new name); `400` if the new name isn't PascalCase; `404` if `:name`
+ * isn't a component; `409` if the new name is already taken. Cross-document
+ * instance references are the editor's responsibility, not the route's.
+ */
+export type ComponentRenameResult = ComponentDoc;
+export declare const componentRenameResultSchema: z.ZodType<ComponentDoc, z.ZodTypeDef, ComponentDoc>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,93 @@
+import { assetEntrySchema, assetManifestSchema, componentDocSchema, tokensDocSchema, } from '@vieda/ir';
+import { z } from 'zod';
+/**
+ * Maximum size of a single uploaded asset. Kept safely under Vercel's ~4.5MB
+ * serverless request/response body limit, since asset bytes flow through the
+ * cloud function in both directions. Enforced by the cloud upload route, the
+ * local editor server, and a `vd publish` pre-check so all three agree.
+ */
+export const MAX_ASSET_BYTES = 4 * 1024 * 1024;
+/** An empty manifest — the "no assets" state, used as a parse/consumer default. */
+export const EMPTY_ASSET_MANIFEST = { schemaVersion: 1, assets: [] };
+/** MIME type by extension, for uploads that arrive without a content type. */
+export const CONTENT_TYPE_BY_EXT = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    svg: 'image/svg+xml',
+};
+/**
+ * Bare, lowercased file extension, or null when there isn't a usable one.
+ * Shared so the local and cloud upload handlers derive it identically.
+ */
+export function assetExtOf(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot < 0 || dot === filename.length - 1)
+        return null;
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return /^[a-z0-9]+$/.test(ext) ? ext : null;
+}
+/** Stored content type: the provided one, else inferred from the extension. */
+export function assetContentType(ext, provided) {
+    return provided || CONTENT_TYPE_BY_EXT[ext] || 'application/octet-stream';
+}
+/** Recursively sort object keys (arrays keep their order). */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, canonical(v)]));
+    }
+    return value;
+}
+/**
+ * Deterministic JSON serialization: independent of object key order and (via
+ * codepoint key sorting, not localeCompare) of the machine's locale. Both
+ * sync-state checks build on it — the CLI hashes it into design/version.json,
+ * and the cloud compares Draft vs latest Version canonical strings directly.
+ * Array order is preserved: it's meaningful in documents (children).
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(canonical(value));
+}
+export const versionMetaSchema = z.object({
+    id: z.string(),
+    number: z.number().int().positive(),
+    label: z.string().nullable(),
+    createdAt: z.string(),
+    createdBy: z.object({ email: z.string(), name: z.string().optional() }),
+    basedOnVersionId: z.string().nullable(),
+});
+/**
+ * Contents of `design/version.json` — written by `vd pull` and `vd publish`
+ * to record which published Version the local design files correspond to.
+ * `digest` is the CLI's canonical sha256 over the whole snapshot (components
+ * + tokens + assets manifest); `vd generate` recomputes it against the local
+ * files to detect modifications since the pull/publish and stamps generated
+ * headers accordingly.
+ */
+export const designVersionFileSchema = z.object({
+    schemaVersion: z.literal(1),
+    version: versionMetaSchema,
+    digest: z.string(),
+});
+/**
+ * Validates a pulled snapshot with the exact document schemas the compiler
+ * uses locally, so a bad payload fails loudly before touching design files.
+ */
+export const versionSnapshotSchema = z.object({
+    meta: versionMetaSchema,
+    components: z.array(componentDocSchema),
+    tokens: tokensDocSchema,
+    // Defaulted so Versions published before assets existed still validate.
+    assets: assetManifestSchema.default(EMPTY_ASSET_MANIFEST),
+});
+export const assetUploadResultSchema = assetEntrySchema;
+export const assetRenameResultSchema = assetEntrySchema;
+export const componentRenameResultSchema = componentDocSchema;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@vieda/api-contract",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@vieda/ir": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}