feat: expose SDK model registry exports (#134)

Expose SDK-owned model registry metadata so consumers can rely on
canonical model names, alias normalization, and filtered model listings
instead of duplicating model literals.
This keeps existing SDK model factories working while adding stable
helpers for registry consumers and preserving `*-latest` as
server-resolved moving targets.

```ts
import { isCanonicalModel, listModels, resolveCanonicalModelAlias } from "@decartai/sdk";

const canonical = resolveCanonicalModelAlias("lucy-pro-v2v"); // "lucy-clip"
const videoModels = listModels({ kind: "video", canonicalOnly: true });
const isCanonical = canonical !== undefined && isCanonicalModel(canonical);
```

Validated with unit tests, typecheck, and build.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Expands the SDK’s public surface area around model identifiers and
adds new alias/listing logic; low runtime risk but moderate
compatibility risk for consumers depending on prior exports/types.
> 
> **Overview**
> Adds **public model-registry exports** from the package root
(`CanonicalModel`, `modelAliases`, `isModel`/`isCanonicalModel`,
`resolveModelAlias`/`resolveCanonicalModelAlias`, and `listModels`) so
consumers can normalize model inputs and enumerate available models by
`kind`.
> 
> Introduces explicit **canonical model name schemas** (excluding
`*-latest` and deprecated aliases) while keeping existing model
factories and broader model validation accepting legacy/latest names;
unit tests are expanded to cover the new helpers, listing behavior, and
to assert raw zod schemas are not exported from the root.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a3973ff. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: AdirAmsalem

packages/sdk/src/index.ts

@@ -47,16 +47,25 @@ export type {
 export type { ConnectionState } from "./realtime/types";
 export type { WebRTCStats } from "./realtime/webrtc-stats";
 export {
+  type CanonicalModel,
   type CustomModelDefinition,
   type ImageModelDefinition,
   type ImageModels,
+  isCanonicalModel,
   isImageModel,
+  isModel,
   isRealtimeModel,
   isVideoModel,
+  type ListedModelDefinition,
+  listModels,
   type Model,
   type ModelDefinition,
+  type ModelKind,
+  modelAliases,
   models,
   type RealTimeModels,
+  resolveCanonicalModelAlias,
+  resolveModelAlias,
   type VideoModelDefinition,
   type VideoModels,
 } from "./shared/model";

packages/sdk/src/shared/model.ts

@@ -1,18 +1,43 @@
 import { z } from "zod";
 import { createModelNotFoundError } from "../utils/errors";
 
+const CANONICAL_MODEL_NAMES = [
+  "lucy-2.1",
+  "lucy-2.1-vton",
+  "lucy-vton-2",
+  "lucy-restyle-2",
+  "lucy-clip",
+  "lucy-image-2",
+] as const;
+
+const CANONICAL_REALTIME_MODEL_NAMES = ["lucy-2.1", "lucy-2.1-vton", "lucy-vton-2", "lucy-restyle-2"] as const;
+const CANONICAL_VIDEO_MODEL_NAMES = [
+  "lucy-clip",
+  "lucy-2.1",
+  "lucy-2.1-vton",
+  "lucy-vton-2",
+  "lucy-restyle-2",
+] as const;
+const CANONICAL_IMAGE_MODEL_NAMES = ["lucy-image-2"] as const;
+
+export const canonicalRealtimeModels = z.enum(CANONICAL_REALTIME_MODEL_NAMES);
+export const canonicalVideoModels = z.enum(CANONICAL_VIDEO_MODEL_NAMES);
+export const canonicalImageModels = z.enum(CANONICAL_IMAGE_MODEL_NAMES);
+export const canonicalModelSchema = z.enum(CANONICAL_MODEL_NAMES);
+export type CanonicalModel = z.infer<typeof canonicalModelSchema>;
+
 /**
  * Map of deprecated model names to their canonical replacements.
  * Old names still work but will log a deprecation warning.
  */
-const MODEL_ALIASES: Record<string, string> = {
+export const modelAliases = {
   mirage_v2: "lucy-restyle-2",
   "lucy-vton": "lucy-2.1-vton",
   "lucy-2.1-vton-2": "lucy-vton-2",
   "lucy-pro-v2v": "lucy-clip",
   "lucy-restyle-v2v": "lucy-restyle-2",
   "lucy-pro-i2i": "lucy-image-2",
-};
+} as const satisfies Record<string, CanonicalModel>;
 
 const _warnedAliases = new Set<string>();
 
@@ -22,7 +47,7 @@ export function _resetDeprecationWarnings(): void {
 }
 
 function warnDeprecated(model: string): void {
-  const canonical = MODEL_ALIASES[model];
+  const canonical = modelAliases[model as keyof typeof modelAliases];
   if (canonical && !_warnedAliases.has(model)) {
     _warnedAliases.add(model);
     console.warn(
@@ -92,6 +117,44 @@ export function isImageModel(model: string): model is ImageModels {
   return imageModels.safeParse(model).success;
 }
 
+export function isModel(model: string): model is Model {
+  return modelSchema.safeParse(model).success;
+}
+
+export function isCanonicalModel(model: string): model is CanonicalModel {
+  return canonicalModelSchema.safeParse(model).success;
+}
+
+/**
+ * Resolve deprecated aliases to canonical model names and pass accepted model names through unchanged.
+ * Latest aliases pass through unchanged because they are server-side moving targets. This is a pure normalization helper
+ * and does not emit deprecation warnings.
+ */
+export function resolveModelAlias(model: string): Model | undefined {
+  const canonical = modelAliases[model as keyof typeof modelAliases];
+  if (canonical) {
+    return canonical;
+  }
+
+  const parsedModel = modelSchema.safeParse(model);
+  return parsedModel.success ? parsedModel.data : undefined;
+}
+
+/**
+ * Resolve deprecated aliases and canonical inputs to stable canonical model names.
+ * Latest aliases are server-side moving targets, so they intentionally return undefined. This is a pure normalization
+ * helper and does not emit deprecation warnings.
+ */
+export function resolveCanonicalModelAlias(model: string): CanonicalModel | undefined {
+  const canonical = modelAliases[model as keyof typeof modelAliases];
+  if (canonical) {
+    return canonical;
+  }
+
+  const parsedModel = canonicalModelSchema.safeParse(model);
+  return parsedModel.success ? parsedModel.data : undefined;
+}
+
 const fileInputSchema = z.union([
   z.instanceof(File),
   z.instanceof(Blob),
@@ -497,6 +560,34 @@ const _models = {
   },
 } as const;
 
+export type ModelKind = "realtime" | "video" | "image";
+export type ListedModelDefinition = ModelDefinition & { kind: ModelKind };
+
+const modelKinds = ["realtime", "video", "image"] as const satisfies readonly ModelKind[];
+const canonicalSchemasByKind = {
+  realtime: canonicalRealtimeModels,
+  video: canonicalVideoModels,
+  image: canonicalImageModels,
+} as const;
+
+/**
+ * List SDK model definitions by kind.
+ * When canonicalOnly is true, deprecated and latest aliases are excluded per kind. Models available in multiple kinds
+ * are returned once per kind with the same name and different kind values.
+ */
+export function listModels(options: { kind?: ModelKind; canonicalOnly?: boolean } = {}): ListedModelDefinition[] {
+  const kinds = options.kind ? [options.kind] : modelKinds;
+
+  return kinds.flatMap((kind) => {
+    return Object.values(_models[kind])
+      .filter(
+        (modelDefinition) =>
+          !options.canonicalOnly || canonicalSchemasByKind[kind].safeParse(modelDefinition.name).success,
+      )
+      .map((modelDefinition) => ({ ...modelDefinition, kind }) as ListedModelDefinition);
+  });
+}
+
 export const models = {
   /**
    * Get a realtime streaming model identifier.

packages/sdk/tests/unit.test.ts

@@ -1,8 +1,33 @@
 import { HttpResponse, http } from "msw";
 import { setupServer } from "msw/node";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { createDecartClient, isRealtimeModel, isVideoModel, models } from "../src/index.js";
-import { _resetDeprecationWarnings } from "../src/shared/model.js";
+import * as publicSdk from "../src/index.js";
+import {
+  type CanonicalModel,
+  createDecartClient,
+  isCanonicalModel,
+  isModel,
+  isRealtimeModel,
+  isVideoModel,
+  type ListedModelDefinition,
+  listModels,
+  type ModelKind,
+  modelAliases,
+  models,
+  resolveCanonicalModelAlias,
+  resolveModelAlias,
+} from "../src/index.js";
+import {
+  _resetDeprecationWarnings,
+  canonicalImageModels,
+  canonicalModelSchema,
+  canonicalRealtimeModels,
+  canonicalVideoModels,
+  imageModels,
+  modelSchema,
+  realtimeModels,
+  videoModels,
+} from "../src/shared/model.js";
 
 const MOCK_RESPONSE_DATA = new Uint8Array([0x00, 0x01, 0x02]).buffer;
 const TEST_API_KEY = "test-api-key";
@@ -3267,6 +3292,150 @@ describe("CustomModelDefinition", () => {
 });
 
 describe("Canonical Model Names", () => {
+  describe("Public model registry exports", () => {
+    const latestAliases = [
+      "lucy-latest",
+      "lucy-vton-latest",
+      "lucy-restyle-latest",
+      "lucy-clip-latest",
+      "lucy-image-latest",
+    ];
+    const deprecatedAliases = [
+      "mirage_v2",
+      "lucy-vton",
+      "lucy-2.1-vton-2",
+      "lucy-pro-v2v",
+      "lucy-restyle-v2v",
+      "lucy-pro-i2i",
+    ];
+
+    it("canonical schemas exclude deprecated and latest aliases", () => {
+      for (const alias of [...latestAliases, ...deprecatedAliases]) {
+        expect(canonicalModelSchema.safeParse(alias).success).toBe(false);
+      }
+
+      expect(canonicalRealtimeModels.options).toEqual(["lucy-2.1", "lucy-2.1-vton", "lucy-vton-2", "lucy-restyle-2"]);
+      expect(canonicalVideoModels.options).toEqual([
+        "lucy-clip",
+        "lucy-2.1",
+        "lucy-2.1-vton",
+        "lucy-vton-2",
+        "lucy-restyle-2",
+      ]);
+      expect(canonicalImageModels.options).toEqual(["lucy-image-2"]);
+      expect(canonicalRealtimeModels.safeParse("lucy-2.1").success).toBe(true);
+      expect(canonicalRealtimeModels.safeParse("lucy-latest").success).toBe(false);
+      expect(canonicalVideoModels.safeParse("lucy-clip").success).toBe(true);
+      expect(canonicalVideoModels.safeParse("lucy-pro-v2v").success).toBe(false);
+      expect(canonicalImageModels.safeParse("lucy-image-2").success).toBe(true);
+      expect(canonicalImageModels.safeParse("lucy-image-latest").success).toBe(false);
+    });
+
+    it("public model schemas still accept deprecated and latest aliases", () => {
+      for (const model of [...latestAliases, ...deprecatedAliases]) {
+        expect(modelSchema.safeParse(model).success).toBe(true);
+      }
+
+      expect(realtimeModels.safeParse("lucy-latest").success).toBe(true);
+      expect(realtimeModels.safeParse("mirage_v2").success).toBe(true);
+      expect(videoModels.safeParse("lucy-clip-latest").success).toBe(true);
+      expect(videoModels.safeParse("lucy-pro-v2v").success).toBe(true);
+      expect(imageModels.safeParse("lucy-image-latest").success).toBe(true);
+      expect(imageModels.safeParse("lucy-pro-i2i").success).toBe(true);
+    });
+
+    it("resolves model aliases while preserving accepted latest aliases", () => {
+      expect(modelAliases["lucy-pro-v2v"]).toBe("lucy-clip");
+      expect(resolveModelAlias("lucy-pro-v2v")).toBe("lucy-clip");
+      expect(resolveModelAlias("lucy-clip")).toBe("lucy-clip");
+      expect(resolveModelAlias("lucy-latest")).toBe("lucy-latest");
+      expect(resolveModelAlias("unknown-model")).toBeUndefined();
+    });
+
+    it("resolves only stable canonical names for canonical alias resolution", () => {
+      expect(resolveCanonicalModelAlias("lucy-pro-v2v")).toBe("lucy-clip");
+      expect(resolveCanonicalModelAlias("lucy-clip")).toBe("lucy-clip");
+      expect(resolveCanonicalModelAlias("lucy-latest")).toBeUndefined();
+      expect(resolveCanonicalModelAlias("unknown-model")).toBeUndefined();
+    });
+
+    it("validates models through public helper functions instead of root zod exports", () => {
+      expect(isModel("lucy-latest")).toBe(true);
+      expect(isModel("unknown-model")).toBe(false);
+      expect(isCanonicalModel("lucy-clip")).toBe(true);
+      expect(isCanonicalModel("lucy-latest")).toBe(false);
+    });
+
+    it("does not emit deprecation warnings from alias resolution helpers", () => {
+      _resetDeprecationWarnings();
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      expect(resolveModelAlias("lucy-pro-v2v")).toBe("lucy-clip");
+      expect(resolveCanonicalModelAlias("lucy-pro-v2v")).toBe("lucy-clip");
+      expect(warnSpy).not.toHaveBeenCalled();
+
+      warnSpy.mockRestore();
+    });
+
+    it("lists all models when called without options", () => {
+      const listedModels = listModels();
+
+      expect(listedModels).toHaveLength(26);
+      expect(listedModels.some((model) => model.kind === "realtime" && model.name === "lucy-2.1")).toBe(true);
+      expect(listedModels.some((model) => model.kind === "video" && model.name === "lucy-clip")).toBe(true);
+      expect(listedModels.some((model) => model.kind === "image" && model.name === "lucy-image-2")).toBe(true);
+    });
+
+    it("filters by kind without excluding latest or deprecated aliases", () => {
+      const realtimeModels = listModels({ kind: "realtime" });
+      const realtimeNames = realtimeModels.map((model) => model.name);
+
+      expect(realtimeModels.every((model) => model.kind === "realtime")).toBe(true);
+      expect(realtimeNames).toContain("lucy-latest");
+      expect(realtimeNames).toContain("mirage_v2");
+    });
+
+    it("lists canonical model definitions without latest or deprecated aliases", () => {
+      const listedModels = listModels({ canonicalOnly: true });
+      const listedNames = listedModels.map((model) => model.name);
+
+      for (const alias of [...latestAliases, ...deprecatedAliases]) {
+        expect(listedNames).not.toContain(alias);
+      }
+      expect(listedModels.every((model) => canonicalModelSchema.safeParse(model.name).success)).toBe(true);
+    });
+
+    it("preserves model kind for dual-kind canonical names", () => {
+      const lucyModels = listModels({ canonicalOnly: true }).filter((model) => model.name === "lucy-2.1");
+
+      expect(lucyModels).toHaveLength(2);
+      expect(lucyModels.map((model) => model.kind).sort()).toEqual(["realtime", "video"]);
+    });
+
+    it("supports consumer-style imports from the package root", () => {
+      const kind: ModelKind = "video";
+      const canonicalModel: CanonicalModel = resolveCanonicalModelAlias("lucy-pro-v2v") ?? "lucy-clip";
+      const listedModels: ListedModelDefinition[] = listModels({ kind, canonicalOnly: true });
+
+      expect(canonicalModel).toBe("lucy-clip");
+      expect(isCanonicalModel(canonicalModel)).toBe(true);
+      expect(listedModels.every((model) => model.kind === kind)).toBe(true);
+    });
+
+    it("does not expose raw zod schemas from the package root", () => {
+      expect("canonicalModelSchema" in publicSdk).toBe(false);
+      expect("canonicalRealtimeModels" in publicSdk).toBe(false);
+      expect("canonicalVideoModels" in publicSdk).toBe(false);
+      expect("canonicalImageModels" in publicSdk).toBe(false);
+      expect("modelSchema" in publicSdk).toBe(false);
+      expect("realtimeModels" in publicSdk).toBe(false);
+      expect("videoModels" in publicSdk).toBe(false);
+      expect("imageModels" in publicSdk).toBe(false);
+      expect("modelInputSchemas" in publicSdk).toBe(false);
+      expect("modelDefinitionSchema" in publicSdk).toBe(false);
+    });
+  });
+
   describe("Realtime canonical models", () => {
     it("lucy-2.1 canonical name works", () => {
       const model = models.realtime("lucy-2.1");