@molecule/api-resource-ai-models 1.0.2 → 1.2.0

package/dist/types.d.ts

@@ -232,6 +232,60 @@ export interface ModelDefinition {
         }[];
         multiplier: number;
     };
+    /**
+     * A price change the provider has ANNOUNCED with a dated effective instant,
+     * staged ahead of time. Until `effectiveFrom` the model bills at the base
+     * rates above; from that instant on, these rates replace them.
+     *
+     * This exists because the freshness gate can only ever see prices that are
+     * ALREADY live: it diffs the catalog against models.dev's *current* rates, so
+     * a change announced today and effective in three days is invisible to it
+     * until after it lands — and the cron runs every 8h, so the catalog would
+     * under-meter for up to a third of a day at whatever the new rate is. Landing
+     * the new numbers early is not an option either: that over-bills every turn
+     * until the switch (the exact mistake the removed DeepSeek peak windows made
+     * for weeks against the free-tier default model). Staging with a timestamp is
+     * the only form that is correct on BOTH sides of the instant, and it needs no
+     * one awake at the switch.
+     *
+     * Applies to the BASE rates only — a `regionPricing` entry is a different
+     * host's rate card (a US re-host does not reprice because the native provider
+     * did) and is never touched by a scheduled change.
+     *
+     * `peakPricing` here, when declared, replaces the model's peak windows from
+     * the same instant; when omitted, the model's existing windows carry through
+     * unchanged. To schedule the END of peak pricing, declare an explicit
+     * `{ windows: [], multiplier: 1 }`.
+     *
+     * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()`, and every
+     * consumer reaches it through `modelRegionRates()` / `priceMultiplierAt()` /
+     * the `withEffectivePricing()` projection the list handler serves — so a
+     * scheduled change lands everywhere at once with no follow-up edit. Once the
+     * instant has passed, fold the rates into the base fields and delete this
+     * (the freshness gate now verifies them against models.dev normally).
+     */
+    scheduledPricing?: {
+        /** ISO-8601 UTC instant the new rates take effect. */
+        effectiveFrom: string;
+        /** Input price per million *uncached* tokens in USD, from `effectiveFrom`. */
+        inputPricePerMTok: number;
+        /** Output price per million tokens in USD, from `effectiveFrom`. */
+        outputPricePerMTok: number;
+        /** Prompt-cache *read* price per million tokens in USD, from `effectiveFrom`. */
+        cacheReadPricePerMTok: number;
+        /** Prompt-cache *write* price per million tokens in USD, from `effectiveFrom`. */
+        cacheWritePricePerMTok: number;
+        /** Peak-hour pricing from `effectiveFrom` (omitted → existing windows carry through). */
+        peakPricing?: {
+            windows: {
+                startMinuteUtc: number;
+                endMinuteUtc: number;
+            }[];
+            multiplier: number;
+        };
+        /** Where the change was announced, for the re-verify pass after it lands. */
+        source?: string;
+    };
     /**
      * Fast-mode ("priority speed") pricing — the per-MTok rates billed when a
      * request runs with the provider's fast/priority tier (e.g. Anthropic's
@@ -282,6 +336,35 @@ export interface ModelDefinition {
      * or its past usage silently meters as free. Omit entirely for active models.
      */
     disabled?: boolean;
+    /**
+     * The id of the NEWER-generation model that replaces this one, set on the
+     * OLDER entry and naming its successor (e.g. `qwen3.7-max` carries
+     * `supersededBy: 'qwen3.8-max'`).
+     *
+     * A superseded model is NOT selectable — like {@link disabled} it is excluded
+     * from `MODEL_IDS`, `getAvailableModels()`, the `GET /ai/models` listing and
+     * the client-side picker partitions, so a user is only ever offered the
+     * newest generation of a family. It differs from `disabled` in *why* and in
+     * what it points at: a disabled model is one the provider retired (it can no
+     * longer answer), whereas a superseded model is usually still served upstream
+     * and simply has nothing to offer over its successor — and the successor id
+     * is a real migration target, so a saved selection can resolve forward
+     * (`resolveSelectableModelId`) instead of silently falling back to the
+     * platform default.
+     *
+     * `getModel(id)` STILL returns a superseded entry — historical usage must stay
+     * priceable, so NEVER delete one.
+     *
+     * Set this ONLY when the successor covers the same TIER. A cheaper or
+     * specialist tier with no newer equivalent is NOT superseded merely because
+     * its version number is lower (Google's sole pro tier `gemini-3.1-pro-preview`
+     * alongside the newer flash flagship; `qwen3-coder-plus`; `kimi-k2.7-code`) —
+     * hiding those would leave a provider with no cheap option. Mark those
+     * {@link deprecatedAt} at most. The invariant is enforced by
+     * `__tests__/lookup.test.ts`: two selectable models of the same family at
+     * different versions fail unless listed there as a documented exception.
+     */
+    supersededBy?: string;
 }
 /**
  * The model ids the SERVER falls back to per mode/job when the user hasn't

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-ai-models",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "AI model catalog — server-side source of truth plus an authentication-gated discovery endpoint",
   "type": "module",
   "main": "dist/index.js",