@shop-os/modelkit 0.1.11 → 0.2.0

package/CHANGELOG.md

@@ -9,7 +9,27 @@ header in the release PR.
 
 ## [Unreleased]
 
-## [0.1.11] - unreleased (publish pending)
+## [0.2.0] - 2026-09-14
+
+### Added
+- `CatalogModelSchema` and `CatalogSchema` (`src/catalog/schema.ts`): Zod schema mirroring
+  `CatalogModel` field for field, tolerating unknown keys. Active rows need `display`, active
+  text rows need `capabilities.contextWindow`, `replacedBy` must not equal `id`, and ids and
+  aliases stay globally unique. `MODELS` passes it.
+- `liveCatalog` (`src/catalog/live.ts`): the shared live catalog, starting as `MODELS`.
+- `primeCatalog` and `resetLiveCatalog` (`src/catalog/load.ts`): fetch, validate and swap the
+  live catalog from `GET /models/catalog`, with `If-None-Match`, a `CatalogCache` last-good
+  fallback, the `MODELS` snapshot fallback, and a background refresh every `ttlMs`. Never
+  throws. Exported from both the node entry and `@shop-os/modelkit/catalog`.
+- `fileCatalogCache` (`src/catalog/file-cache.ts`, node entry only): file-backed last-good
+  store, written atomically via `path + ".tmp"` plus rename.
+- `Catalog.replace(rows)`: atomic swap of the id and alias maps.
+
+### Changed
+- `createModelKit` reads `liveCatalog` when no `catalogOverride` is given, so a primed catalog
+  reaches an existing kit without a rebuild.
+
+## [0.1.11] - 2026-09-13
 
 ### Added
 - `display.logo` on every catalog row except `mmaudio` and `bg-remove`: text rows carry the
@@ -189,8 +209,9 @@ First publish, renamed from `@shop-os/model-sdk`.
 - Keys per tier (pro, enterprise with per-provider fallback); one retry classifier, one error
   type, one usage event with the canonical id.
 
-[Unreleased]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.1.11...dev
-[0.1.11]: https://github.com/Shop-OS/shopos-backend-ts/compare/f0981d9b9...dev
+[Unreleased]: https://github.com/Shop-OS/shopos-backend-ts/compare/modelkit-0.2.0...dev
+[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
 [0.1.9]: https://github.com/Shop-OS/shopos-backend-ts/compare/1958a5615...dev
 [0.1.8]: https://github.com/Shop-OS/shopos-backend-ts/commit/9661a109d

package/dist/catalog.cjs

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/catalog-entry.ts
 var catalog_entry_exports = {};
 __export(catalog_entry_exports, {
+  ADAPTER_IDS: () => ADAPTER_IDS,
   Catalog: () => Catalog,
+  CatalogModelSchema: () => CatalogModelSchema,
+  CatalogSchema: () => CatalogSchema,
   IMAGE_MODELS: () => IMAGE_MODELS,
   MODELS: () => MODELS,
   ModelKitError: () => ModelKitError,
@@ -28,7 +31,10 @@ __export(catalog_entry_exports, {
   TEXT_MODELS: () => TEXT_MODELS,
   VIDEO_MODELS: () => VIDEO_MODELS,
   isModelKitError: () => isModelKitError,
+  liveCatalog: () => liveCatalog,
   nearestAspectRatio: () => nearestAspectRatio,
+  primeCatalog: () => primeCatalog,
+  resetLiveCatalog: () => resetLiveCatalog,
   resolveAudioOptions: () => resolveAudioOptions,
   resolveImageOptions: () => resolveImageOptions,
   resolveOptions: () => resolveOptions,
@@ -131,6 +137,14 @@ var Catalog = class _Catalog {
       ...rows
     ]);
   }
+  /** Atomically swap every row. Builds the maps first so a bad batch throws before anything changes. */
+  replace(rows) {
+    const next = new _Catalog(rows);
+    this.byId.clear();
+    this.byAlias.clear();
+    for (const [id, model] of next.byId) this.byId.set(id, model);
+    for (const [alias, id] of next.byAlias) this.byAlias.set(alias, id);
+  }
 };
 
 // src/catalog/image.ts
@@ -1821,6 +1835,387 @@ var MODELS = [
   ...OTHER_MODELS
 ];
 
+// src/catalog/schema.ts
+var import_zod = require("zod");
+var ADAPTER_IDS = [
+  "ai-sdk-text",
+  "google-image",
+  "openai-image",
+  "google-genai",
+  "ark",
+  "fal",
+  "replicate",
+  "prodia",
+  "higgsfield",
+  "xai-video"
+];
+var ModelTypeSchema = import_zod.z.enum(["text", "image", "video", "audio", "upscale", "bg-remove"]);
+var LifecycleSchema = import_zod.z.enum(["active", "deprecated", "retired"]);
+var AdapterSchema = import_zod.z.enum(ADAPTER_IDS);
+var AspectRatioSchema = import_zod.z.enum([
+  "1:1",
+  "16:9",
+  "9:16",
+  "4:3",
+  "3:4",
+  "3:2",
+  "2:3",
+  "4:5",
+  "5:4",
+  "21:9",
+  "9:21",
+  "97:30",
+  "adaptive"
+]);
+var ImageSizeSchema = import_zod.z.enum(["512", "1K", "2K", "4K"]);
+var VideoResolutionSchema = import_zod.z.enum(["360p", "480p", "720p", "768p", "1080p", "2k", "4k"]);
+var ImageQualitySchema = import_zod.z.enum(["auto", "low", "medium", "high", "xhigh", "max"]);
+var OutputFormatSchema = import_zod.z.enum(["png", "jpeg", "webp"]);
+var RequiredInputSchema = import_zod.z.enum(["firstFrame", "sourceVideo", "references"]);
+var SupportedOptionSchema = import_zod.z.enum([
+  "seed",
+  "quality",
+  "negativePrompt",
+  "cfgScale",
+  "generateAudio",
+  "promptExpansion",
+  "lastFrame",
+  "count",
+  "outputFormat",
+  "scaleFactor",
+  "safetySettings",
+  "temperature",
+  "upscale",
+  "watermark",
+  "safetyChecker",
+  "instrumental"
+]);
+var UsageUnitSchema = import_zod.z.enum([
+  "tokens",
+  "images",
+  "seconds",
+  "reported_cost_usd",
+  "compute_seconds"
+]);
+var PricingKindSchema = import_zod.z.enum(["token", "image_size", "video_per_second", "flat"]);
+var ProviderOptionValueSchema = import_zod.z.lazy(
+  () => import_zod.z.union([
+    import_zod.z.string(),
+    import_zod.z.number(),
+    import_zod.z.boolean(),
+    import_zod.z.array(ProviderOptionValueSchema),
+    import_zod.z.record(import_zod.z.string(), ProviderOptionValueSchema)
+  ])
+);
+var ProviderOptionsSchema = import_zod.z.record(import_zod.z.string(), import_zod.z.record(import_zod.z.string(), ProviderOptionValueSchema));
+var ReferenceLimitsSchema = import_zod.z.looseObject({
+  images: import_zod.z.number().optional(),
+  videos: import_zod.z.number().optional(),
+  audios: import_zod.z.number().optional(),
+  total: import_zod.z.number().optional(),
+  audioOnly: import_zod.z.boolean().optional()
+});
+var ModelConstraintsSchema = import_zod.z.looseObject({
+  aspectRatios: import_zod.z.array(AspectRatioSchema).optional(),
+  sizes: import_zod.z.array(ImageSizeSchema).optional(),
+  resolutions: import_zod.z.array(VideoResolutionSchema).optional(),
+  durations: import_zod.z.union([import_zod.z.looseObject({ min: import_zod.z.number(), max: import_zod.z.number() }), import_zod.z.array(import_zod.z.number())]).optional(),
+  durationPresets: import_zod.z.array(import_zod.z.number()).optional(),
+  qualityOptions: import_zod.z.array(import_zod.z.string()).optional(),
+  exactSizes: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional(),
+  references: ReferenceLimitsSchema.optional(),
+  requires: import_zod.z.array(RequiredInputSchema).optional(),
+  supports: import_zod.z.array(SupportedOptionSchema).optional(),
+  ratioIgnoredWith: import_zod.z.array(import_zod.z.enum(["firstFrame", "sourceVideo"])).optional()
+});
+var MediaRefSchema = import_zod.z.union([
+  import_zod.z.looseObject({ url: import_zod.z.string(), label: import_zod.z.string().optional() }),
+  import_zod.z.looseObject({
+    bytes: import_zod.z.instanceof(Uint8Array),
+    mime: import_zod.z.string(),
+    label: import_zod.z.string().optional()
+  })
+]);
+var ImageSafetySettingSchema = import_zod.z.looseObject({ category: import_zod.z.string(), threshold: import_zod.z.string() });
+var UpscaleOptionsSchema = import_zod.z.looseObject({
+  enhanceModel: import_zod.z.string().optional(),
+  subjectDetection: import_zod.z.string().optional(),
+  faceEnhancement: import_zod.z.boolean().optional(),
+  faceEnhancementCreativity: import_zod.z.number().optional(),
+  faceEnhancementStrength: import_zod.z.number().optional()
+});
+var DefaultsSchema = import_zod.z.looseObject({
+  references: import_zod.z.array(MediaRefSchema).optional(),
+  aspectRatio: AspectRatioSchema.optional(),
+  size: ImageSizeSchema.optional(),
+  exactSize: import_zod.z.string().optional(),
+  quality: ImageQualitySchema.optional(),
+  seed: import_zod.z.number().optional(),
+  count: import_zod.z.number().optional(),
+  outputFormat: OutputFormatSchema.optional(),
+  scaleFactor: import_zod.z.number().optional(),
+  safetySettings: import_zod.z.array(ImageSafetySettingSchema).optional(),
+  temperature: import_zod.z.number().optional(),
+  upscale: UpscaleOptionsSchema.optional(),
+  firstFrame: MediaRefSchema.optional(),
+  lastFrame: MediaRefSchema.optional(),
+  sourceVideo: MediaRefSchema.optional(),
+  referenceImages: import_zod.z.array(MediaRefSchema).optional(),
+  referenceVideos: import_zod.z.array(MediaRefSchema).optional(),
+  referenceAudios: import_zod.z.array(MediaRefSchema).optional(),
+  resolution: VideoResolutionSchema.optional(),
+  durationSeconds: import_zod.z.number().optional(),
+  generateAudio: import_zod.z.boolean().optional(),
+  negativePrompt: import_zod.z.string().optional(),
+  cfgScale: import_zod.z.number().optional(),
+  promptExpansion: import_zod.z.enum(["fast", "balanced", "quality"]).optional(),
+  watermark: import_zod.z.boolean().optional(),
+  safetyChecker: import_zod.z.boolean().optional(),
+  mode: import_zod.z.enum(["standard", "pro"]).optional(),
+  instrumental: import_zod.z.boolean().optional()
+});
+var CatalogDisplaySchema = import_zod.z.looseObject({
+  provider: import_zod.z.string(),
+  description: import_zod.z.string(),
+  logo: import_zod.z.string().optional(),
+  costTier: import_zod.z.union([import_zod.z.literal(1), import_zod.z.literal(2), import_zod.z.literal(3)]).optional(),
+  recommended: import_zod.z.boolean().optional(),
+  sortOrder: import_zod.z.number().optional(),
+  chat: import_zod.z.looseObject({
+    providerOptions: ProviderOptionsSchema.optional(),
+    temperature: import_zod.z.number().optional()
+  }).optional()
+});
+var CatalogCapabilitiesSchema = import_zod.z.looseObject({
+  acceptsSourceVideo: import_zod.z.boolean().optional(),
+  framesExcludeReferences: import_zod.z.boolean().optional(),
+  reasoning: import_zod.z.boolean().optional(),
+  vision: import_zod.z.boolean().optional(),
+  contextWindow: import_zod.z.number().optional()
+});
+var CatalogModelSchemaBase = import_zod.z.looseObject({
+  id: import_zod.z.string().min(1),
+  aliases: import_zod.z.array(import_zod.z.string()).default([]),
+  label: import_zod.z.string().min(1),
+  type: ModelTypeSchema,
+  adapter: AdapterSchema,
+  providerModelId: import_zod.z.string().min(1),
+  lifecycle: LifecycleSchema,
+  replacedBy: import_zod.z.string().optional(),
+  exposure: import_zod.z.enum(["catalog", "internal"]),
+  constraints: ModelConstraintsSchema,
+  defaults: DefaultsSchema,
+  providerOptions: ProviderOptionsSchema.optional(),
+  usage: import_zod.z.looseObject({
+    unit: UsageUnitSchema,
+    slug: import_zod.z.string().optional(),
+    providerLabel: import_zod.z.string().optional()
+  }),
+  pricingKind: PricingKindSchema,
+  display: CatalogDisplaySchema.optional(),
+  capabilities: CatalogCapabilitiesSchema.optional()
+}).superRefine((row, ctx) => {
+  if (row.lifecycle === "active" && !row.display) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["display"],
+      message: "active rows need display"
+    });
+  }
+  if (row.lifecycle === "active" && row.type === "text" && !row.capabilities?.contextWindow) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["capabilities", "contextWindow"],
+      message: "active text rows need contextWindow"
+    });
+  }
+  if (row.replacedBy !== void 0 && row.replacedBy === row.id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["replacedBy"],
+      message: "replacedBy must not equal id"
+    });
+  }
+});
+var CatalogModelSchema = CatalogModelSchemaBase;
+var CatalogSchema = import_zod.z.array(CatalogModelSchemaBase).superRefine((rows, ctx) => {
+  const seenIds = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    if (seenIds.has(row.id)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "id"],
+        message: `Duplicate model id "${row.id}"`
+      });
+    } else {
+      seenIds.set(row.id, index);
+    }
+  });
+  const seenAliases = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    row.aliases.forEach((alias, aliasIndex) => {
+      const path = [index, "aliases", aliasIndex];
+      if (alias === row.id || seenIds.has(alias)) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `Alias "${alias}" collides with a model id`
+        });
+        return;
+      }
+      if (seenAliases.has(alias)) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `Duplicate alias "${alias}"`
+        });
+      } else {
+        seenAliases.set(alias, index);
+      }
+    });
+  });
+});
+
+// src/catalog/live.ts
+var liveCatalog = new Catalog(MODELS);
+
+// src/catalog/load.ts
+var memo;
+var timer;
+var revision;
+var origin = "snapshot";
+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 };
+}
+function logPrimed(logger, result) {
+  const { origin: loggedOrigin, rowCount: loggedCount, revision: loggedRevision } = result;
+  logger.info("[modelkit] catalog primed", {
+    origin: loggedOrigin,
+    rowCount: loggedCount,
+    revision: loggedRevision
+  });
+}
+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}"`;
+  const res = await fetchImpl(`${source.baseUrl}/models/catalog`, {
+    headers,
+    signal: AbortSignal.timeout(source.timeoutMs ?? 1e4)
+  });
+  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);
+  if (rev === void 0) return { rows, fromCache: false };
+  return { rows, revision: rev, fromCache: false };
+}
+async function writeCache(source, logger, rows, rev) {
+  if (!source.cache) return;
+  try {
+    await source.cache.set(JSON.stringify({ rows, revision: rev }));
+  } catch (err) {
+    logger.warn("[modelkit] catalog cache write failed", err);
+  }
+}
+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;
+      logPrimed(logger, result2);
+      return result2;
+    }
+    liveCatalog.replace(fetched.rows);
+    origin = "remote";
+    revision = fetched.revision;
+    await writeCache(source, logger, fetched.rows, fetched.revision);
+    const result = { 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);
+    try {
+      const cached = await source.cache?.get();
+      if (!cached) throw new Error("no cached catalog");
+      const { rows, revision: rev } = parseEnvelope(JSON.parse(cached));
+      liveCatalog.replace(rows);
+      origin = "last-good";
+      revision = rev;
+      const result = { 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;
+      const result = {
+        origin,
+        rowCount: rowCount(),
+        error
+      };
+      logPrimed(logger, result);
+      return result;
+    }
+  }
+}
+async function refresh(source, logger) {
+  try {
+    const fetched = await fetchRemote(source, logger);
+    if ("kept" in fetched) return;
+    liveCatalog.replace(fetched.rows);
+    origin = "remote";
+    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;
+  const logger = source.logger ?? console;
+  memo = 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?.();
+    }
+    return result;
+  });
+  return memo;
+}
+function resetLiveCatalog() {
+  if (timer !== void 0) {
+    clearInterval(timer);
+    timer = void 0;
+  }
+  memo = void 0;
+  revision = void 0;
+  origin = "snapshot";
+  liveCatalog.replace([...MODELS]);
+}
+
 // src/resolve-options.ts
 var SIZE_ORDER = ["512", "1K", "2K", "4K"];
 var RESOLUTION_ORDER = ["360p", "480p", "720p", "768p", "1080p", "2k", "4k"];