@shop-os/modelkit 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -9,6 +9,44 @@ header in the release PR.
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-09-15
+
+### Changed
+- `display.sortOrder` sorts descending: a higher number shows first, so a new model takes the next number up. No published row set it before.
+
+### Fixed
+- `primeCatalog` treats a remote response with zero rows as a failure and keeps the last-good or snapshot rows, so a pro-backend whose catalog table is not seeded yet cannot empty every consumer's pickers.
+
+## [0.2.2] - 2026-09-15
+
+Option audit against provider docs, limited to options a product surface sets.
+
+### Added
+- Veo 3.1, 3.1 Fast and 3.1 Lite accept `seed` (sent as `config.seed`).
+- Seedream 5.0 Pro accepts `outputFormat` png/jpeg (sent as `output_format`; webp is coerced to png with a warning).
+- Gemini 3 image rows declare `references.images: 14`, the provider cap.
+
+### Fixed
+- `liveCatalog` and the prime state are one process-wide singleton (on `globalThis`). The root and `./catalog` bundles each carried their own copy, so a server that primed through the root entry still served the snapshot to code importing `@shop-os/modelkit/catalog`.
+
+### Changed
+- gpt-image-2.5-sunburst/flare `qualityOptions` add `xhigh` and `max`.
+- Veo 3.1 Fast and Lite durations add 6 s. Veo 3.1 Lite drops `references` (not supported for Lite).
+- Gemini Omni rows allow 3 reference videos (was 1).
+- Seedance rows declare `ratioIgnoredWith: ["firstFrame", "sourceVideo"]` to match the adapter.
+- kling-v3-omni-video aspect ratios are 16:9, 9:16, 1:1, adaptive (provider list).
+- seedream-4.5 drops the 1K tier (provider minimum 2K). gemini-2.5-flash-image is 1K only. muse-image-1.0 drops 4:5 and 5:4.
+- qwen-image-2-pro no longer requires a reference image.
+- Prodia nano-banana rows drop `seed` (the adapter never sent it).
+
+## [0.2.1] - 2026-09-15
+
+### Added
+- `gpt-image-2`, `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` declare `outputFormat`; the `openai-image` adapter sends `output_format` (png or jpeg) and labels the result mime to match.
+
+### Changed
+- `outputFormat: "webp"` on GPT image models is coerced to png with an `option_ignored` warning: the API returns PNG bytes for webp (openai/openai-node#1850).
+
 ## [0.2.0] - 2026-09-14
 
 ### Added
@@ -210,6 +248,8 @@ First publish, renamed from `@shop-os/model-sdk`.
   type, one usage event with the canonical id.
 
 [Unreleased]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.2.0...dev
+[0.2.2]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.2.1...modelkit-0.2.2
+[0.2.1]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.2.0...modelkit-0.2.1
 [0.2.0]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.1.11...modelkit-0.2.0
 [0.1.11]: https://github.com/Shop-OS/shopos-backend-ts/compare/f0981d9b9...bb3b16354
 [0.1.10]: https://github.com/Shop-OS/shopos-backend-ts/compare/f17e822e2...f0981d9b9

package/dist/catalog.cjs

@@ -32,6 +32,7 @@ __export(catalog_entry_exports, {
   VIDEO_MODELS: () => VIDEO_MODELS,
   isModelKitError: () => isModelKitError,
   liveCatalog: () => liveCatalog,
+  liveState: () => liveState,
   nearestAspectRatio: () => nearestAspectRatio,
   primeCatalog: () => primeCatalog,
   resetLiveCatalog: () => resetLiveCatalog,
@@ -162,7 +163,13 @@ var GEMINI_RATIOS = [
   "5:4",
   "adaptive"
 ];
-function geminiImage(id, label, aliases, sizes, display, exposure) {
+function geminiImage(id, label, aliases, sizes, display, exposure, references) {
+  const constraints = {
+    aspectRatios: [...GEMINI_RATIOS],
+    sizes,
+    supports: ["safetySettings", "temperature"]
+  };
+  if (references !== void 0) constraints.references = references;
   const model = {
     id,
     aliases,
@@ -172,11 +179,7 @@ function geminiImage(id, label, aliases, sizes, display, exposure) {
     providerModelId: id,
     lifecycle: "active",
     exposure,
-    constraints: {
-      aspectRatios: [...GEMINI_RATIOS],
-      sizes,
-      supports: ["safetySettings", "temperature"]
-    },
+    constraints,
     defaults: { size: "1K", aspectRatio: "1:1" },
     usage: { ...IMAGE_USAGE, slug: "gemini" },
     pricingKind: "image_size",
@@ -195,7 +198,8 @@ var IMAGE_MODELS = [
       description: "Create stunning, production-quality visuals with exceptional realism, detail, and typography. Best for campaigns, e-commerce, product photography, and hero creatives.",
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
-    "catalog"
+    "catalog",
+    { images: 14 }
   ),
   geminiImage(
     "gemini-3.1-flash-image-preview",
@@ -208,7 +212,8 @@ var IMAGE_MODELS = [
       description: "Generate high-quality images at speed. Perfect for brainstorming, moodboards, concept testing, creative exploration, and large batch workflows.",
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
-    "catalog"
+    "catalog",
+    { images: 14 }
   ),
   geminiImage(
     "gemini-3.1-flash-lite-image",
@@ -220,14 +225,15 @@ var IMAGE_MODELS = [
       description: "The fastest and most affordable image model. Ideal for rapid drafts, bulk exploration, and iterative concept testing at 1K resolution.",
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
-    "catalog"
+    "catalog",
+    { images: 14 }
   ),
   // trigger-workflows validates 1K only; pricing seeds 2K/4K rows so allow all three.
   geminiImage(
     "gemini-2.5-flash-image",
     "Gemini 2.5 Flash Image",
     [],
-    ["1K", "2K", "4K"],
+    ["1K"],
     {
       provider: "google",
       description: "Nano Banana (legacy Gemini 2.5 Flash Image) native image generation and editing model for high-volume, low-latency creative workflows."
@@ -258,7 +264,7 @@ var IMAGE_MODELS = [
       sizes: ["1K", "2K", "4K"],
       qualityOptions: ["auto", "low", "medium", "high"],
       references: { images: 16 },
-      supports: ["quality", "count"]
+      supports: ["quality", "count", "outputFormat"]
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE, slug: "gpt" },
@@ -278,7 +284,7 @@ var IMAGE_MODELS = [
     adapter: "openai-image",
     providerModelId: "gpt-image-2.5-sunburst",
     lifecycle: "active",
-    exposure: "internal",
+    exposure: "catalog",
     constraints: {
       exactSizes: {
         "1:1": "1024x1024",
@@ -291,15 +297,16 @@ var IMAGE_MODELS = [
       },
       aspectRatios: ["1:1", "3:2", "2:3", "16:9", "9:16", "4:5", "5:4", "adaptive"],
       sizes: ["1K", "2K", "4K"],
-      qualityOptions: ["auto", "low", "medium", "high"],
+      qualityOptions: ["auto", "low", "medium", "high", "xhigh", "max"],
       references: { images: 16 },
-      supports: ["quality", "count"]
+      supports: ["quality", "count", "outputFormat"]
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE },
     pricingKind: "image_size",
     display: {
       provider: "openai",
+      sortOrder: 20,
       description: "OpenAI's most capable GPT Image 2.5 tier, built for editing precision; takes text and image input and outputs images in low, medium, high, xhigh, or max quality."
     }
   },
@@ -312,7 +319,7 @@ var IMAGE_MODELS = [
     adapter: "openai-image",
     providerModelId: "gpt-image-2.5-flare",
     lifecycle: "active",
-    exposure: "internal",
+    exposure: "catalog",
     constraints: {
       exactSizes: {
         "1:1": "1024x1024",
@@ -325,15 +332,16 @@ var IMAGE_MODELS = [
       },
       aspectRatios: ["1:1", "3:2", "2:3", "16:9", "9:16", "4:5", "5:4", "adaptive"],
       sizes: ["1K", "2K", "4K"],
-      qualityOptions: ["auto", "low", "medium", "high"],
+      qualityOptions: ["auto", "low", "medium", "high", "xhigh", "max"],
       references: { images: 16 },
-      supports: ["quality", "count"]
+      supports: ["quality", "count", "outputFormat"]
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE },
     pricingKind: "image_size",
     display: {
       provider: "openai",
+      sortOrder: 10,
       description: "OpenAI's fastest GPT Image 2.5 tier for high-quality everyday image generation and editing; takes text and image input and outputs images."
     }
   },
@@ -357,8 +365,6 @@ var IMAGE_MODELS = [
         "2:3",
         "3:4",
         "9:16",
-        "4:5",
-        "5:4",
         "9:21",
         "adaptive"
       ],
@@ -390,7 +396,7 @@ var IMAGE_MODELS = [
       references: { images: 10 },
       // Ark's Images API has no output-format, quality or count field; only
       // the seed is forwarded, so anything else must warn, not vanish.
-      supports: ["seed"]
+      supports: ["seed", "outputFormat"]
     },
     defaults: { size: "1K", aspectRatio: "1:1" },
     usage: { ...IMAGE_USAGE },
@@ -426,7 +432,7 @@ var IMAGE_MODELS = [
         "21:9",
         "9:21"
       ],
-      sizes: ["1K", "2K", "4K"],
+      sizes: ["2K", "4K"],
       references: { images: 10 },
       supports: ["seed"]
     },
@@ -478,7 +484,7 @@ var IMAGE_MODELS = [
       aspectRatios: ["1:1", "2:3", "3:2", "4:3", "3:4", "4:5", "5:4", "9:16", "16:9", "21:9"],
       sizes: ["1K", "2K", "4K"],
       requires: ["references"],
-      supports: ["seed"]
+      supports: []
     },
     defaults: { size: "1K", aspectRatio: "1:1" },
     usage: { ...IMAGE_USAGE },
@@ -503,7 +509,7 @@ var IMAGE_MODELS = [
       aspectRatios: ["1:1", "2:3", "3:4", "4:3", "9:16", "16:9", "21:9"],
       sizes: ["1K"],
       requires: ["references"],
-      supports: ["seed"]
+      supports: []
     },
     defaults: { size: "1K", aspectRatio: "1:1" },
     usage: { ...IMAGE_USAGE },
@@ -555,7 +561,6 @@ var IMAGE_MODELS = [
       aspectRatios: ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"],
       sizes: [],
       references: { images: 1 },
-      requires: ["references"],
       supports: []
     },
     defaults: { aspectRatio: "1:1" },
@@ -1274,7 +1279,7 @@ var VIDEO_MODELS = [
       resolutions: ["720p", "1080p", "4k"],
       durations: [8],
       references: { images: 3 },
-      supports: ["lastFrame"]
+      supports: ["lastFrame", "seed"]
     },
     defaults: { durationSeconds: 8, resolution: "720p", aspectRatio: "16:9" },
     usage: { ...VIDEO_USAGE, slug: "veo" },
@@ -1302,9 +1307,9 @@ var VIDEO_MODELS = [
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["720p", "1080p", "4k"],
-      durations: [4, 8],
+      durations: [4, 6, 8],
       references: { images: 3 },
-      supports: ["lastFrame"]
+      supports: ["lastFrame", "seed"]
     },
     defaults: { durationSeconds: 8, resolution: "720p", aspectRatio: "16:9" },
     usage: { ...VIDEO_USAGE },
@@ -1331,9 +1336,8 @@ var VIDEO_MODELS = [
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["720p", "1080p"],
-      durations: [4, 8],
-      references: { images: 3 },
-      supports: ["lastFrame"]
+      durations: [4, 6, 8],
+      supports: ["lastFrame", "seed"]
     },
     defaults: { durationSeconds: 8, resolution: "720p", aspectRatio: "16:9" },
     usage: { ...VIDEO_USAGE },
@@ -1365,7 +1369,7 @@ var VIDEO_MODELS = [
       // reference clip keeps its own framing.
       aspectRatios: [...OMNI_RATIOS],
       durations: [3, 4, 5, 6, 7, 8, 9, 10],
-      references: { images: 6, videos: 1 },
+      references: { images: 6, videos: 3 },
       supports: []
     },
     defaults: {},
@@ -1391,7 +1395,7 @@ var VIDEO_MODELS = [
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["360p", "720p", "1080p", "4k"],
       durations: [3, 4, 5, 6, 7, 8, 9, 10],
-      references: { images: 6, videos: 1 },
+      references: { images: 6, videos: 3 },
       supports: []
     },
     defaults: {},
@@ -1420,7 +1424,7 @@ var VIDEO_MODELS = [
       durations: { min: 4, max: 15 },
       durationPresets: [4, 6, 8, 10, 12, 15],
       references: { images: 9, videos: 3, audios: 3, audioOnly: false },
-      ratioIgnoredWith: ["firstFrame"],
+      ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark"]
     },
     defaults: {
@@ -1452,7 +1456,7 @@ var VIDEO_MODELS = [
       resolutions: ["480p", "720p"],
       durations: { min: 4, max: 15 },
       references: { images: 9, videos: 3, audios: 3, audioOnly: false },
-      ratioIgnoredWith: ["firstFrame"],
+      ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark"]
     },
     defaults: {
@@ -1485,7 +1489,7 @@ var VIDEO_MODELS = [
       resolutions: ["480p", "720p", "1080p"],
       durations: { min: 4, max: 30 },
       references: { images: 30, videos: 10, audios: 10 },
-      ratioIgnoredWith: ["firstFrame"],
+      ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark"]
     },
     defaults: {
@@ -1604,18 +1608,7 @@ var VIDEO_MODELS = [
     lifecycle: "active",
     exposure: "catalog",
     constraints: {
-      aspectRatios: [
-        "1:1",
-        "16:9",
-        "9:16",
-        "4:3",
-        "3:4",
-        "3:2",
-        "2:3",
-        "21:9",
-        "4:5",
-        "adaptive"
-      ],
+      aspectRatios: [...KLING_RATIOS],
       resolutions: ["720p", "1080p"],
       durations: { min: 3, max: 15 },
       references: { images: 7 },
@@ -2077,30 +2070,34 @@ var CatalogSchema = import_zod.z.array(CatalogModelSchemaBase).superRefine((rows
 });
 
 // src/catalog/live.ts
-var liveCatalog = new Catalog(MODELS);
+var KEY = /* @__PURE__ */ Symbol.for("@shop-os/modelkit/live-catalog");
+var store = globalThis;
+var liveState = store[KEY] ??= {
+  catalog: new Catalog(MODELS),
+  memo: void 0,
+  timer: void 0,
+  revision: void 0,
+  origin: "snapshot"
+};
+var liveCatalog = liveState.catalog;
 
 // src/catalog/load.ts
-var memo;
-var timer;
-var revision;
-var origin = "snapshot";
+var import_zod2 = require("zod");
 function rowCount() {
   return liveCatalog.list({ lifecycle: ["active", "deprecated", "retired"] }).length;
 }
 function authHeaders(auth) {
   return "bearer" in auth ? { Authorization: `Bearer ${auth.bearer}` } : { "x-api-key": auth.apiKey };
 }
-function describeError(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-function parseEnvelope(json) {
-  if (typeof json !== "object" || json === null || !("rows" in json)) {
-    throw new Error("invalid catalog response: missing rows");
-  }
-  const rows = CatalogSchema.parse(json.rows);
-  const rev = json.revision;
-  if (typeof rev === "string") return { rows, revision: rev };
-  return { rows };
+var EnvelopeSchema = import_zod2.z.object({
+  rows: CatalogSchema,
+  revision: import_zod2.z.string().optional()
+});
+function toEnvelope(data) {
+  if (data.rows.length === 0) throw new Error("invalid catalog response: no rows");
+  const envelope = { rows: data.rows };
+  if (data.revision !== void 0) envelope.revision = data.revision;
+  return envelope;
 }
 function logPrimed(logger, result) {
   const { origin: loggedOrigin, rowCount: loggedCount, revision: loggedRevision } = result;
@@ -2113,7 +2110,7 @@ function logPrimed(logger, result) {
 async function fetchRemote(source, logger) {
   const fetchImpl = source.fetch ?? globalThis.fetch;
   const headers = authHeaders(source.auth);
-  if (revision !== void 0) headers["If-None-Match"] = `"${revision}"`;
+  if (liveState.revision !== void 0) headers["If-None-Match"] = `"${liveState.revision}"`;
   const res = await fetchImpl(`${source.baseUrl}/models/catalog`, {
     headers,
     signal: AbortSignal.timeout(source.timeoutMs ?? 1e4)
@@ -2121,7 +2118,9 @@ async function fetchRemote(source, logger) {
   if (res.status === 304) return { kept: true };
   if (!res.ok) throw new Error(`catalog fetch failed with status ${res.status}`);
   const json = await res.json();
-  const { rows, revision: rev } = parseEnvelope(json);
+  const parsed = EnvelopeSchema.safeParse(json);
+  if (!parsed.success) throw new Error("invalid catalog response: missing rows");
+  const { rows, revision: rev } = toEnvelope(parsed.data);
   if (rev === void 0) return { rows, fromCache: false };
   return { rows, revision: rev, fromCache: false };
 }
@@ -2137,40 +2136,46 @@ async function prime(source, logger) {
   try {
     const fetched = await fetchRemote(source, logger);
     if ("kept" in fetched) {
-      const result2 = { origin, rowCount: rowCount() };
-      if (revision !== void 0) result2.revision = revision;
+      const result2 = { origin: liveState.origin, rowCount: rowCount() };
+      if (liveState.revision !== void 0) result2.revision = liveState.revision;
       logPrimed(logger, result2);
       return result2;
     }
     liveCatalog.replace(fetched.rows);
-    origin = "remote";
-    revision = fetched.revision;
+    liveState.origin = "remote";
+    liveState.revision = fetched.revision;
     await writeCache(source, logger, fetched.rows, fetched.revision);
-    const result = { origin, rowCount: rowCount() };
+    const result = { origin: liveState.origin, rowCount: rowCount() };
     if (fetched.revision !== void 0) result.revision = fetched.revision;
     logPrimed(logger, result);
     return result;
   } catch (err) {
     logger.warn("[modelkit] catalog remote failed, trying cache", err);
-    const error = describeError(err);
+    const error = err instanceof Error ? err.message : String(err);
     try {
       const cached = await source.cache?.get();
       if (!cached) throw new Error("no cached catalog");
-      const { rows, revision: rev } = parseEnvelope(JSON.parse(cached));
+      const cachedParsed = EnvelopeSchema.safeParse(JSON.parse(cached));
+      if (!cachedParsed.success) throw new Error("invalid catalog response: missing rows");
+      const { rows, revision: rev } = toEnvelope(cachedParsed.data);
       liveCatalog.replace(rows);
-      origin = "last-good";
-      revision = rev;
-      const result = { origin, rowCount: rowCount(), error };
+      liveState.origin = "last-good";
+      liveState.revision = rev;
+      const result = {
+        origin: liveState.origin,
+        rowCount: rowCount(),
+        error
+      };
       if (rev !== void 0) result.revision = rev;
       logPrimed(logger, result);
       return result;
     } catch (cacheErr) {
       logger.warn("[modelkit] catalog cache failed, using snapshot", cacheErr);
       liveCatalog.replace([...MODELS]);
-      origin = "snapshot";
-      revision = void 0;
+      liveState.origin = "snapshot";
+      liveState.revision = void 0;
       const result = {
-        origin,
+        origin: liveState.origin,
         rowCount: rowCount(),
         error
       };
@@ -2184,35 +2189,35 @@ async function refresh(source, logger) {
     const fetched = await fetchRemote(source, logger);
     if ("kept" in fetched) return;
     liveCatalog.replace(fetched.rows);
-    origin = "remote";
-    revision = fetched.revision;
+    liveState.origin = "remote";
+    liveState.revision = fetched.revision;
     await writeCache(source, logger, fetched.rows, fetched.revision);
   } catch (err) {
     logger.warn("[modelkit] catalog refresh failed, keeping current rows", err);
   }
 }
 function primeCatalog(source) {
-  if (memo) return memo;
+  if (liveState.memo) return liveState.memo;
   const logger = source.logger ?? console;
-  memo = prime(source, logger).then((result) => {
+  const pending = prime(source, logger).then((result) => {
     const ttlMs = source.ttlMs ?? 3e5;
-    if (ttlMs > 0 && timer === void 0) {
-      timer = setInterval(() => void refresh(source, logger), ttlMs);
-      const maybeUnref = timer;
-      maybeUnref.unref?.();
+    if (ttlMs > 0 && liveState.timer === void 0) {
+      liveState.timer = setInterval(() => void refresh(source, logger), ttlMs);
+      liveState.timer.unref?.();
     }
     return result;
   });
-  return memo;
+  liveState.memo = pending;
+  return pending;
 }
 function resetLiveCatalog() {
-  if (timer !== void 0) {
-    clearInterval(timer);
-    timer = void 0;
+  if (liveState.timer !== void 0) {
+    clearInterval(liveState.timer);
+    liveState.timer = void 0;
   }
-  memo = void 0;
-  revision = void 0;
-  origin = "snapshot";
+  liveState.memo = void 0;
+  liveState.revision = void 0;
+  liveState.origin = "snapshot";
   liveCatalog.replace([...MODELS]);
 }