@shop-os/modelkit 0.3.8 → 0.4.1

package/dist/index.d.cts

@@ -184,6 +184,8 @@ interface VideoToolSubmission {
     responseUrl: string;
     cancelUrl: string;
     output: VideoToolOutputSpec;
+    /** Epoch ms when the kit submitted the job; the result's usage `latencyMs` is measured from it. */
+    submittedAt?: number;
 }
 type VideoToolStatus = "queued" | "running" | "completed";
 interface VideoToolResult {
@@ -523,6 +525,13 @@ interface UsageEvent {
     inputTokens?: number;
     outputTokens?: number;
     reportedCostUsd?: number;
+    /**
+     * Wall time of the kit call that produced this event, in ms: from dispatch to the
+     * provider's final answer (a video's polling included; a multi-step text call's tool
+     * steps included). Absent only where the kit never saw the start (a video tool whose
+     * submission carries no `submittedAt`).
+     */
+    latencyMs?: number;
     raw?: unknown;
 }
 type ProviderKeyName = "openai" | "anthropic" | "google" | "xai" | "perplexity" | "deepseek" | "moonshot" | "minimax" | "ark" | "fal" | "replicate" | "prodia" | "higgsfield" | "cloudflare";
@@ -605,7 +614,9 @@ interface CallContext {
 
 /** Provider body or the lifted detail (Gemini blockReason, fal body.detail). */
 type ProviderErrorBody = string | JsonValue;
-type ModelKitErrorCode = "unknown_model" | "unsupported_option" | "missing_input" | "content_blocked" | "provider_rejected" | "timeout" | "auth" | "network" | "rate_limited";
+type ModelKitErrorCode = "unknown_model" | "unsupported_option" | "missing_input" | "content_blocked" | "provider_rejected"
+/** The provider account is out of credit or quota (HTTP 402 and its body spellings). Never retried. */
+ | "provider_billing" | "timeout" | "auth" | "network" | "rate_limited";
 interface ModelKitErrorInit {
     code: ModelKitErrorCode;
     message: string;
@@ -1230,7 +1241,7 @@ declare function keysFromEnv(env: NodeJS.ProcessEnv, prefix?: string): ProviderK
 
 /**
  * One classifier for every adapter. Never retry safety blocks,
- * content_policy_violation, or 4xx other than 429. Retry 429, 5xx, timeouts
+ * content_policy_violation, billing failures, or 4xx other than 429. Retry 429, 5xx, timeouts
  * and network failures. Adapters must not stack their own retry loop on top.
  */
 declare function classifyHttpError(status: number | undefined, body: ProviderErrorBody, provider: string, model?: string): ModelKitError;

package/dist/index.d.ts

@@ -184,6 +184,8 @@ interface VideoToolSubmission {
     responseUrl: string;
     cancelUrl: string;
     output: VideoToolOutputSpec;
+    /** Epoch ms when the kit submitted the job; the result's usage `latencyMs` is measured from it. */
+    submittedAt?: number;
 }
 type VideoToolStatus = "queued" | "running" | "completed";
 interface VideoToolResult {
@@ -523,6 +525,13 @@ interface UsageEvent {
     inputTokens?: number;
     outputTokens?: number;
     reportedCostUsd?: number;
+    /**
+     * Wall time of the kit call that produced this event, in ms: from dispatch to the
+     * provider's final answer (a video's polling included; a multi-step text call's tool
+     * steps included). Absent only where the kit never saw the start (a video tool whose
+     * submission carries no `submittedAt`).
+     */
+    latencyMs?: number;
     raw?: unknown;
 }
 type ProviderKeyName = "openai" | "anthropic" | "google" | "xai" | "perplexity" | "deepseek" | "moonshot" | "minimax" | "ark" | "fal" | "replicate" | "prodia" | "higgsfield" | "cloudflare";
@@ -605,7 +614,9 @@ interface CallContext {
 
 /** Provider body or the lifted detail (Gemini blockReason, fal body.detail). */
 type ProviderErrorBody = string | JsonValue;
-type ModelKitErrorCode = "unknown_model" | "unsupported_option" | "missing_input" | "content_blocked" | "provider_rejected" | "timeout" | "auth" | "network" | "rate_limited";
+type ModelKitErrorCode = "unknown_model" | "unsupported_option" | "missing_input" | "content_blocked" | "provider_rejected"
+/** The provider account is out of credit or quota (HTTP 402 and its body spellings). Never retried. */
+ | "provider_billing" | "timeout" | "auth" | "network" | "rate_limited";
 interface ModelKitErrorInit {
     code: ModelKitErrorCode;
     message: string;
@@ -1230,7 +1241,7 @@ declare function keysFromEnv(env: NodeJS.ProcessEnv, prefix?: string): ProviderK
 
 /**
  * One classifier for every adapter. Never retry safety blocks,
- * content_policy_violation, or 4xx other than 429. Retry 429, 5xx, timeouts
+ * content_policy_violation, billing failures, or 4xx other than 429. Retry 429, 5xx, timeouts
  * and network failures. Adapters must not stack their own retry loop on top.
  */
 declare function classifyHttpError(status: number | undefined, body: ProviderErrorBody, provider: string, model?: string): ModelKitError;

package/dist/index.js

@@ -222,35 +222,43 @@ var IMAGE_MODELS = [
     GEMINI_PROMPT_MAX_CHARS,
     NANO_BANANA_2_1_RATIOS
   ),
-  geminiImage(
-    "gemini-3-pro-image-preview",
-    "Nano Banana Pro",
-    ["nb-pro"],
-    ["1K", "2K", "4K"],
-    {
-      provider: "google",
-      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"
-    },
-    ["cowork", "space_builder"],
-    { images: 14 },
-    GEMINI_PROMPT_MAX_CHARS
-  ),
-  geminiImage(
-    "gemini-3.1-flash-image-preview",
-    "Nano Banana 2",
-    ["nb-2"],
-    // Flash 3.1 is the only Gemini image model with the 512 tier.
-    ["512", "1K", "2K", "4K"],
-    {
-      provider: "google",
-      description: "Generate high-quality images at speed. Perfect for brainstorming, concept boards, concept testing, creative exploration, and large batch workflows.",
-      logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
-    },
-    ["cowork", "space_builder"],
-    { images: 14 },
-    GEMINI_PROMPT_MAX_CHARS
-  ),
+  // Google retired the -preview endpoints for the GA ids; the catalog ids stay because they
+  // are pricing keys and stored model ids.
+  {
+    ...geminiImage(
+      "gemini-3-pro-image-preview",
+      "Nano Banana Pro",
+      ["nb-pro"],
+      ["1K", "2K", "4K"],
+      {
+        provider: "google",
+        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"
+      },
+      ["cowork", "space_builder"],
+      { images: 14 },
+      GEMINI_PROMPT_MAX_CHARS
+    ),
+    providerModelId: "gemini-3-pro-image"
+  },
+  {
+    ...geminiImage(
+      "gemini-3.1-flash-image-preview",
+      "Nano Banana 2",
+      ["nb-2"],
+      // Flash 3.1 is the only Gemini image model with the 512 tier.
+      ["512", "1K", "2K", "4K"],
+      {
+        provider: "google",
+        description: "Generate high-quality images at speed. Perfect for brainstorming, concept boards, concept testing, creative exploration, and large batch workflows.",
+        logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
+      },
+      ["cowork", "space_builder"],
+      { images: 14 },
+      GEMINI_PROMPT_MAX_CHARS
+    ),
+    providerModelId: "gemini-3.1-flash-image"
+  },
   geminiImage(
     "gemini-3.1-flash-lite-image",
     "Nano Banana Lite",
@@ -1384,6 +1392,7 @@ var OMNI_PROMPT = { referenceSyntax: "caption", maxChars: 5e4 };
 var BYTEDANCE_LOGO = "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/3bba5d81-4e57-4e71-911b-cdfa05acca2c_compressed.png";
 var GOOGLE_LOGO2 = "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png";
 var VIDEO_MODELS = [
+  // Google shuts down the Veo 3.1 previews and Omni Flash 1.0 on 2026-10-22.
   {
     id: "veo-3.1",
     aliases: [
@@ -1396,8 +1405,9 @@ var VIDEO_MODELS = [
     type: "video",
     adapter: "google-genai",
     providerModelId: "veo-3.1-generate-preview",
-    lifecycle: "active",
-    exposure: ["cowork", "space_builder"],
+    lifecycle: "deprecated",
+    replacedBy: "gemini-omni-1.1-flash",
+    exposure: [],
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["720p", "1080p", "4k"],
@@ -1432,7 +1442,8 @@ var VIDEO_MODELS = [
     type: "video",
     adapter: "google-genai",
     providerModelId: "veo-3.1-fast-generate-preview",
-    lifecycle: "active",
+    lifecycle: "deprecated",
+    replacedBy: "gemini-omni-1.1-flash",
     exposure: [],
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
@@ -1462,7 +1473,8 @@ var VIDEO_MODELS = [
     type: "video",
     adapter: "google-genai",
     providerModelId: "veo-3.1-lite-generate-preview",
-    lifecycle: "active",
+    lifecycle: "deprecated",
+    replacedBy: "gemini-omni-1.1-flash",
     exposure: [],
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
@@ -1493,8 +1505,9 @@ var VIDEO_MODELS = [
     type: "video",
     adapter: "google-genai",
     providerModelId: "gemini-omni-flash-preview",
-    lifecycle: "active",
-    exposure: ["cowork", "space_builder"],
+    lifecycle: "deprecated",
+    replacedBy: "gemini-omni-1.1-flash",
+    exposure: [],
     constraints: {
       // 1.0 rejects `resolution`; it renders 720p. No defaults: the adapter
       // sends ratio and duration only when the caller set them, so a
@@ -2049,7 +2062,8 @@ var VIDEO_MODELS = [
     },
     defaults: {},
     usage: { ...VIDEO_USAGE },
-    pricingKind: "video_per_second",
+    // Higgsfield bills DoP per generation: a fixed-length clip with no duration knob.
+    pricingKind: "flat",
     display: {
       provider: "higgsfield",
       description: "Higgsfield DOP image-to-video model; animates a required first-frame image from a text prompt with an optional last-frame image and motion controls."
@@ -3285,6 +3299,36 @@ function describeThrown(cause) {
 
 // src/retry.ts
 var textBody = z6.string();
+var BILLING_CODES = /* @__PURE__ */ new Set([
+  "insufficient_quota",
+  "billing_hard_limit_reached",
+  "billing_not_active",
+  "payment_required",
+  "insufficient_balance",
+  "insufficient_credits",
+  "insufficient_credit"
+]);
+var errorCodes = z6.object({
+  code: z6.string().optional(),
+  type: z6.string().optional(),
+  error: z6.object({ code: z6.string().optional(), type: z6.string().optional() }).optional()
+});
+var BILLING_TEXT = /insufficient_quota|payment[ _]required|exhausted balance|insufficient (?:credits?|balance|funds)|billing_hard_limit/i;
+var BILLING_TEXT_STATUSES = /* @__PURE__ */ new Set([403, 429]);
+function billingCode(body) {
+  const parsed = errorCodes.safeParse(body);
+  if (!parsed.success) return false;
+  const { code, type, error } = parsed.data;
+  return [code, type, error?.code, error?.type].some(
+    (value) => value !== void 0 && BILLING_CODES.has(value.toLowerCase())
+  );
+}
+function isBillingFailure(status, body, text2) {
+  if (status === 402) return true;
+  if (status === void 0 || status < 400 || status >= 500) return false;
+  if (billingCode(body)) return true;
+  return BILLING_TEXT_STATUSES.has(status) && BILLING_TEXT.test(text2);
+}
 function classifyHttpError(status, body, provider, model) {
   const asText = textBody.safeParse(body);
   const text2 = asText.success ? asText.data : JSON.stringify(body);
@@ -3293,6 +3337,7 @@ function classifyHttpError(status, body, provider, model) {
   );
   let code = "provider_rejected";
   if (blocked) code = "content_blocked";
+  else if (isBillingFailure(status, body, text2)) code = "provider_billing";
   else if (status === 401 || status === 403) code = "auth";
   else if (status === 429) code = "rate_limited";
   else if (status === 408 || status === 504) code = "timeout";
@@ -3355,12 +3400,11 @@ function sleep(ms, signal) {
       rejectAborted();
       return;
     }
-    let timer;
     const onAbort = () => {
-      if (timer !== void 0) clearTimeout(timer);
+      clearTimeout(timer);
       rejectAborted();
     };
-    timer = setTimeout(() => {
+    const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
       resolve();
     }, ms);
@@ -9150,6 +9194,13 @@ function createModelKit(config, adapters) {
       model: model.id
     });
   }
+  function timed(event, startedAt) {
+    if (event.latencyMs !== void 0) return event;
+    return { ...event, latencyMs: Math.max(0, Date.now() - startedAt) };
+  }
+  function textTimed(event, stepCount, startedAt) {
+    return stepCount === 1 ? timed(event, startedAt) : event;
+  }
   async function emit(event) {
     try {
       await config.onUsage?.(event);
@@ -9233,17 +9284,21 @@ function createModelKit(config, adapters) {
     const abortSignal = combineSignals(req.abortSignal, call.signal);
     if (abortSignal) options.abortSignal = abortSignal;
     if (call.maxRetries !== void 0) options.maxRetries = call.maxRetries;
+    const startedAt = Date.now();
     const result = await aiGenerateImage(options);
     const images = result.images.map(
       (file) => toGeneratedImage({ bytes: file.uint8Array, mime: file.mediaType })
     );
-    const usage2 = {
-      model: model.modelId,
-      provider: model.provider,
-      modality: "IMAGE",
-      unit: "images",
-      quantity: images.length
-    };
+    const usage2 = timed(
+      {
+        model: model.modelId,
+        provider: model.provider,
+        modality: "IMAGE",
+        unit: "images",
+        quantity: images.length
+      },
+      startedAt
+    );
     await emit(usage2);
     return { image: images[0], images, usage: usage2, raw: result, warnings };
   }
@@ -9316,18 +9371,22 @@ function createModelKit(config, adapters) {
     if (providerOptions) options.providerOptions = providerOptions;
     if (abortSignal) options.abortSignal = abortSignal;
     logCoercions(logger, model.modelId, warnings);
+    const startedAt = Date.now();
     const pending = aiGenerateVideo(options);
     let settled;
     let failed = false;
     const done = pending.then(async (result) => {
-      const usage2 = {
-        model: model.modelId,
-        provider: model.provider,
-        modality: "VIDEO",
-        unit: "seconds",
-        quantity: seconds2 ?? 0,
-        ...seconds2 !== void 0 && { durationSeconds: seconds2 }
-      };
+      const usage2 = timed(
+        {
+          model: model.modelId,
+          provider: model.provider,
+          modality: "VIDEO",
+          unit: "seconds",
+          quantity: seconds2 ?? 0,
+          ...seconds2 !== void 0 && { durationSeconds: seconds2 }
+        },
+        startedAt
+      );
       settled = {
         video: { bytes: result.video.uint8Array, mime: result.video.mediaType },
         usage: usage2,
@@ -9384,8 +9443,12 @@ function createModelKit(config, adapters) {
           message: `${adapter.id} cannot generate images`,
           model: model.id
         });
+      const startedAt = Date.now();
       const result = await adapter.generateImage(request, ctx);
-      const usage2 = { ...result.usage, model: model.id, unit: model.usage.unit };
+      const usage2 = timed(
+        { ...result.usage, model: model.id, unit: model.usage.unit },
+        startedAt
+      );
       await emit(usage2);
       const images = result.images.map(toGeneratedImage);
       const first = images[0];
@@ -9428,6 +9491,7 @@ function createModelKit(config, adapters) {
           message: `${adapter.id} cannot generate video`,
           model: model.id
         });
+      const startedAt = Date.now();
       const job = await adapter.generateVideo(request, ctx);
       const result = job.result.bind(job);
       let settled;
@@ -9437,11 +9501,14 @@ function createModelKit(config, adapters) {
         result(opts) {
           if (settled) return settled;
           const pending = result(opts).then(
-            (out) => emit({
-              ...out.usage,
-              model: model.id,
-              unit: model.usage.unit
-            }).then(() => out),
+            async (out) => {
+              const usage2 = timed(
+                { ...out.usage, model: model.id, unit: model.usage.unit },
+                startedAt
+              );
+              await emit(usage2);
+              return { ...out, usage: usage2 };
+            },
             (cause) => {
               settled = void 0;
               throw cause;
@@ -9478,9 +9545,14 @@ function createModelKit(config, adapters) {
           model: model.id
         });
       }
+      const startedAt = Date.now();
       const result = await adapter.generateAudio(resolved, ctx);
-      await emit({ ...result.usage, model: model.id, unit: model.usage.unit });
-      return result;
+      const usage2 = timed(
+        { ...result.usage, model: model.id, unit: model.usage.unit },
+        startedAt
+      );
+      await emit(usage2);
+      return { ...result, usage: usage2 };
     },
     async prepareMediaPart(modelId, ref, mediaType, call = {}) {
       mediaRetryOptions(call);
@@ -9509,11 +9581,13 @@ function createModelKit(config, adapters) {
       const { webhookUrl, ...rest } = call;
       const { adapter, ctx } = videoToolTarget(req.model, rest);
       if (!adapter.submitVideoTool) throw noVideoTools(adapter, ctx.model);
-      return adapter.submitVideoTool(
+      const submittedAt = Date.now();
+      const submission = await adapter.submitVideoTool(
         req,
         ctx,
         webhookUrl !== void 0 ? { webhookUrl } : {}
       );
+      return { ...submission, submittedAt };
     },
     async videoToolStatus(sub, call = {}) {
       const { adapter, ctx } = videoToolTarget(sub.model, call);
@@ -9525,8 +9599,10 @@ function createModelKit(config, adapters) {
       const { adapter, ctx } = videoToolTarget(sub.model, rest);
       if (!adapter.videoToolResult) throw noVideoTools(adapter, ctx.model);
       const result = await adapter.videoToolResult(sub, ctx, webhook);
-      await emit({ ...result.usage, model: ctx.model.id, unit: ctx.model.usage.unit });
-      return result;
+      const base = { ...result.usage, model: ctx.model.id, unit: ctx.model.usage.unit };
+      const usage2 = sub.submittedAt === void 0 ? base : timed(base, sub.submittedAt);
+      await emit(usage2);
+      return { ...result, usage: usage2 };
     },
     async cancelVideoTool(sub, call = {}) {
       const { adapter, ctx } = videoToolTarget(sub.model, call);
@@ -9548,6 +9624,7 @@ function createModelKit(config, adapters) {
         (model) => textTarget(model, call),
         options.providerOptions
       );
+      const startedAt = Date.now();
       const result = await aiGenerateText2({
         ...options,
         ...textAbortOptions(options.abortSignal, call.signal),
@@ -9557,7 +9634,8 @@ function createModelKit(config, adapters) {
           options.prepareStep ?? options.experimental_prepareStep
         )
       });
-      for (const event of steps.usage(result.steps)) await emit(withRowUnit(event));
+      for (const event of steps.usage(result.steps))
+        await emit(textTimed(withRowUnit(event), result.steps.length, startedAt));
       return result;
     },
     streamText(options, call = {}) {
@@ -9568,6 +9646,7 @@ function createModelKit(config, adapters) {
         options.providerOptions
       );
       const callerOnFinish = options.onFinish;
+      const startedAt = Date.now();
       return aiStreamText2({
         ...options,
         ...textAbortOptions(options.abortSignal, call.signal),
@@ -9577,7 +9656,8 @@ function createModelKit(config, adapters) {
           options.prepareStep ?? options.experimental_prepareStep
         ),
         onFinish: async (event) => {
-          for (const usage2 of steps.usage(event.steps)) await emit(withRowUnit(usage2));
+          for (const usage2 of steps.usage(event.steps))
+            await emit(textTimed(withRowUnit(usage2), event.steps.length, startedAt));
           await callerOnFinish?.(event);
         }
       });
@@ -9590,15 +9670,22 @@ function createModelKit(config, adapters) {
         model: languageModel2,
         providerOptions: mergeTextProviderOptions(entry, options.providerOptions)
       };
+      const startedAt = Date.now();
       const result = await aiGenerateObject2(sdkOptions);
       await emit(
-        withRowUnit(textUsageEvent(entry, provider, result.usage, result.providerMetadata))
+        timed(
+          withRowUnit(
+            textUsageEvent(entry, provider, result.usage, result.providerMetadata)
+          ),
+          startedAt
+        )
       );
       return result;
     },
     streamObject(options, call = {}) {
       const { entry, languageModel: languageModel2, provider } = textTarget(options.model, call);
       const callerOnFinish = options.onFinish;
+      const startedAt = Date.now();
       const sdkOptions = {
         ...options,
         ...textAbortOptions(options.abortSignal, call.signal),
@@ -9606,8 +9693,16 @@ function createModelKit(config, adapters) {
         providerOptions: mergeTextProviderOptions(entry, options.providerOptions),
         onFinish: async (event) => {
           await emit(
-            withRowUnit(
-              textUsageEvent(entry, provider, event.usage, event.providerMetadata)
+            timed(
+              withRowUnit(
+                textUsageEvent(
+                  entry,
+                  provider,
+                  event.usage,
+                  event.providerMetadata
+                )
+              ),
+              startedAt
             )
           );
           await callerOnFinish?.(event);