vidspotai-shared 1.0.94 → 1.0.95

package/lib/schemas/videoPlan.schema.d.ts

@@ -676,12 +676,12 @@ export declare const VideoPlanSchema: z.ZodObject<{
         estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
         sceneIndices: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
     }, z.core.$strip>>>;
-    script: z.ZodOptional<z.ZodObject<{
+    script: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
         fullText: z.ZodString;
         wordCount: z.ZodOptional<z.ZodNumber>;
         estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
         wpm: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     music: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodEnum<{
             none: "none";

package/lib/schemas/videoPlan.schema.d.ts.map

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

package/lib/schemas/videoPlan.schema.js

@@ -489,8 +489,18 @@ exports.VideoPlanSchema = zod_1.z.object({
      * Stream L (L-1) — full narration script for L1+ videos. Generated before
      * scenes in script-first authoring (L-3); scenes' voiceoverLines are slices
      * of `script.fullText`. Absent on scene-first (S1/S2/M1) plans.
+     *
+     * Coercion: the planner LLM repeatedly emits `script` as a bare narration
+     * string instead of `{ fullText }` (observed in prod 2026-06-30 — failed all
+     * 3 retries with "expected object, received string", killing the whole
+     * project). A string is unambiguous (it IS the full text), so we normalize it
+     * to `{ fullText }` at the schema boundary rather than burning retries on a
+     * shape the model won't reliably fix. `wordCount`/`estimatedDurationMs` stay
+     * optional and get backfilled downstream.
      */
-    script: exports.ScriptSchema.optional(),
+    script: zod_1.z
+        .preprocess((v) => (typeof v === "string" ? { fullText: v } : v), exports.ScriptSchema)
+        .optional(),
     /** Music recommendation for the whole video. */
     music: zod_1.z
         .object({

package/lib/services/agent/tools/planVideo.tool.d.ts

@@ -332,12 +332,12 @@ declare const OutputSchema: z.ZodObject<{
             estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
             sceneIndices: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
         }, z.core.$strip>>>;
-        script: z.ZodOptional<z.ZodObject<{
+        script: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
             fullText: z.ZodString;
             wordCount: z.ZodOptional<z.ZodNumber>;
             estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
             wpm: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         music: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodEnum<{
                 none: "none";

package/lib/services/aiGen/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,EAAE,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAqJrE"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,EAAE,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAiKrE"}

package/lib/services/aiGen/helpers.js

@@ -5,6 +5,7 @@ exports.getModelsSupportingLastFrame = getModelsSupportingLastFrame;
 exports.modelDeclaresField = modelDeclaresField;
 exports.validateParams = validateParams;
 const aiModels_1 = require("../../globals/aiModels");
+const errors_1 = require("../../utils/errors");
 /**
  * Whether a model supports first-last-frame (FLF) interpolation, i.e. accepts a
  * `lastFrameImageUrl`. The source of truth is the model config: a model declares
@@ -125,9 +126,18 @@ function validateParams(params) {
             }
         }
     }
-    // 4. Fail fast if validation fails
+    // 4. Fail fast if validation fails.
+    // These are DETERMINISTIC input/capability mismatches (a required input the
+    // model needs is absent, an unsupported value/combo, etc.) — an expected
+    // user-input outcome, NOT a server fault. Throw a typed UserFacingError with
+    // CAPABILITY_MISMATCH so it (a) short-circuits the scene retry loop, (b) stays
+    // OFF the pager (errorPaging non-paging set) instead of alerting on-call with
+    // a raw "INTERNAL Validation failed" — e.g. a kling-motion-control job
+    // submitted without its required inputVideoUrl (2026-07-09). The job surfaces
+    // the friendly CAPABILITY_MISMATCH message; the technical detail stays on the
+    // scene for debugging.
     if (errors.length) {
-        throw new Error(`INTERNAL Validation failed: ${errors.join("; ")}`);
+        throw new errors_1.UserFacingError(`Validation failed: ${errors.join("; ")}`, errors_1.USER_FACING_ERROR_CODES.CAPABILITY_MISMATCH);
     }
     return true;
 }

package/lib/services/aiGen/providers/kling/kling.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kling.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/kling/kling.service.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAsBlB;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,wBAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IASxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkD;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;;YAWlE,OAAO;IAgCf,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAoDjC;;;;OAIG;YACW,WAAW;YA6BX,iBAAiB;YA6BjB,qBAAqB;YAgCrB,eAAe;YAkDf,mBAAmB;YAgCnB,uBAAuB;IAwF/B,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW7E,cAAc,IAAI,MAAM;IAexB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAGjD"}
+{"version":3,"file":"kling.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/kling/kling.service.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAsBlB;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,wBAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IASxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkD;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;;YAWlE,OAAO;IAgCf,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAoDjC;;;;OAIG;YACW,WAAW;YA6BX,iBAAiB;YA6BjB,qBAAqB;YAgCrB,eAAe;YAkDf,mBAAmB;YAgCnB,uBAAuB;IAqI/B,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW7E,cAAc,IAAI,MAAM;IAexB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAGjD"}

package/lib/services/aiGen/providers/kling/kling.service.js

@@ -219,25 +219,64 @@ class KlingService extends baseAiGenProvider_service_1.BaseAiGenProviderService
                 // True rate-limit (HTTP 429 without the balance code) — worth retrying with backoff.
                 const isRateLimit = httpStatus === 429 && !isInsufficientBalance;
                 const isRetryable = (isTimeout || isNetworkError || isRateLimit) && !isInsufficientBalance;
-                // Insufficient balance is a critical ops issue — surface immediately to Slack.
+                // Insufficient balance is a billing/account fault an operator must act on
+                // (top up Kling). Classify as ACCOUNT_QUOTA_EXCEEDED so the shared paging
+                // policy (errorPaging.ts) pages ONCE at the scene boundary — consistent
+                // with the Veo billing-depletion path. The top-up detail is logged at
+                // warn (Loki only, no duplicate Slack page) so it stays searchable
+                // without the previous double-page (raw throw here + generic scene page).
                 if (isInsufficientBalance) {
-                    logger_1.logger.error("Kling account balance too low — top up required to continue video generation", {
+                    logger_1.logger.warn("Kling account balance too low — top up required to continue video generation", {
                         endpoint,
                         klingCode,
                         klingMessage: err.response?.data?.message,
                         httpStatus,
                     });
-                    throw err;
+                    throw new errors_1.UserFacingError("This video provider is temporarily unavailable. Please try a different model or retry shortly.", errors_1.USER_FACING_ERROR_CODES.ACCOUNT_QUOTA_EXCEEDED);
                 }
-                // Audio rejected by Kling — pick the user message based on which 1201 variant it is.
+                // Kling code 1201 is a broad "input rejected" family — a user-fixable
+                // input constraint, not a system fault. It fires for AUDIO (avatar /
+                // lip-sync `sound_file`) AND for IMAGE inputs (e.g. an oversized
+                // end-frame `image_tail` on a plain image2video — see the kling-v3.0
+                // end-frame case, 2026-07-09). So only blame audio when audio was
+                // actually part of the request; otherwise the message misleads the
+                // user (and whoever debugs the log) into hunting a non-existent audio
+                // clip. CAPABILITY_MISMATCH keeps it off the pager (errorPaging set).
                 if (isAudioError) {
                     const klingMsg = (err.response?.data?.message ?? "").toLowerCase();
-                    const userMessage = klingMsg.includes("size")
-                        ? "Your audio file is too large for this avatar generation. Please use a shorter audio clip and try again."
-                        : "Your audio format is not supported. Please upload an MP3 or WAV file and try again.";
-                    throw new errors_1.UserFacingError(userMessage);
+                    const isSize = klingMsg.includes("size");
+                    const hasAudioInput = endpoint.includes("avatar") ||
+                        endpoint.includes("lip") ||
+                        !!(body && typeof body === "object" && body.sound_file);
+                    let userMessage;
+                    if (hasAudioInput) {
+                        userMessage = isSize
+                            ? "Your audio clip is too large for this video. Please use a shorter audio clip and try again."
+                            : "Your audio format is not supported. Please upload an MP3 or WAV file and try again.";
+                    }
+                    else {
+                        userMessage = isSize
+                            ? "One of your input images is too large for this model. Please use a smaller image (or remove the end-frame) and try again."
+                            : "One of your inputs was rejected by this model. Please adjust your image or settings and try again.";
+                    }
+                    throw new errors_1.UserFacingError(userMessage, errors_1.USER_FACING_ERROR_CODES.CAPABILITY_MISMATCH);
                 }
                 if (!isRetryable || attempt === maxAttempts) {
+                    // A rate-limit that exhausted its retries is an expected, un-actionable
+                    // condition (Kling throughput saturation) — surface it as a non-paging
+                    // UserFacingError rather than a raw axios 429, so it doesn't page
+                    // on-call. (Genuine 1102 balance depletion is handled above and DOES
+                    // page; ambiguous bare 429s land here and read as rate-limit, which is
+                    // the safe default — rate limits shouldn't page.)
+                    if (isRateLimit) {
+                        logger_1.logger.warn("Kling rate-limited — retries exhausted", {
+                            endpoint,
+                            attempt,
+                            maxAttempts,
+                            httpStatus,
+                        });
+                        throw new errors_1.UserFacingError("This video provider is busy right now. Please retry in a little while.", errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_RATE_LIMITED);
+                    }
                     logger_1.logger.error("Kling API request failed (non-retryable or max attempts reached)", {
                         endpoint,
                         attempt,

package/lib/services/aiGen/providers/pixverse/pixverse.service.d.ts

@@ -2,6 +2,14 @@ import { BaseAiGenProviderService } from "../baseAiGenProvider.service";
 import { CreditUsageParams, VideoGenerationParams, VideoGenerationResult, VideoStatusParams, VideoStatusResult } from "../types";
 export declare class PixVerseService extends BaseAiGenProviderService {
     private readonly baseUrl;
+    /**
+     * Uploads a source image to PixVerse and returns the integer `img_id` that
+     * /img/generate requires. The Upload-Image endpoint accepts either a binary
+     * `image` file or an `image_url` string (multipart/form-data) — we pass the
+     * URL we already have. Note: NO Content-Type header here; fetch sets the
+     * multipart boundary itself when the body is a FormData.
+     */
+    private uploadImage;
     generateVideo(params: VideoGenerationParams): Promise<VideoGenerationResult>;
     checkVideoStatus({ task, outputFilename, outputFilePath, }: VideoStatusParams): Promise<VideoStatusResult>;
     getCreditUsed(params: CreditUsageParams): number;

package/lib/services/aiGen/providers/pixverse/pixverse.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixverse.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/pixverse/pixverse.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AA0FlB,qBAAa,eAAgB,SAAQ,wBAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAKpE,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAyK3B,gBAAgB,CAAC,EACrB,IAAI,EACJ,cAAc,EACd,cAAyB,GAC1B,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0FjD,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAkDjD"}
+{"version":3,"file":"pixverse.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/pixverse/pixverse.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AA0FlB,qBAAa,eAAgB,SAAQ,wBAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAK1E;;;;;;OAMG;YACW,WAAW;IA6CnB,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAgL3B,gBAAgB,CAAC,EACrB,IAAI,EACJ,cAAc,EACd,cAAyB,GAC1B,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0FjD,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAkDjD"}

package/lib/services/aiGen/providers/pixverse/pixverse.service.js

@@ -82,6 +82,52 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
         this.baseUrl = "https://app-api.pixverse.ai/openapi/v2/video";
     }
     // =========================================================
+    // UPLOAD IMAGE (image-to-video prerequisite)
+    // =========================================================
+    /**
+     * Uploads a source image to PixVerse and returns the integer `img_id` that
+     * /img/generate requires. The Upload-Image endpoint accepts either a binary
+     * `image` file or an `image_url` string (multipart/form-data) — we pass the
+     * URL we already have. Note: NO Content-Type header here; fetch sets the
+     * multipart boundary itself when the body is a FormData.
+     */
+    async uploadImage(imageUrl, traceId) {
+        const form = new FormData();
+        form.append("image_url", imageUrl);
+        return (0, transientRetry_1.withTransientRetry)("pixverse:uploadImage", async () => {
+            const resp = await fetch(`https://app-api.pixverse.ai/openapi/v2/image/upload`, {
+                method: "POST",
+                headers: {
+                    "API-KEY": process.env.PIXVERSE_API_KEY,
+                    "Ai-trace-id": traceId,
+                },
+                body: form,
+            });
+            if (!resp.ok) {
+                const errText = await resp.text();
+                throw classifyPixVerseHttpError(resp.status, errText, "uploadImage");
+            }
+            const data = await resp.json();
+            if (data.ErrCode !== undefined && data.ErrCode !== 0) {
+                throw classifyPixVerseApiError(data.ErrCode, data.ErrMsg ?? "", "uploadImage");
+            }
+            const imgId = data?.Resp?.img_id;
+            if (imgId === undefined || imgId === null) {
+                throw new Error("PixVerse image upload did not return img_id");
+            }
+            return Number(imgId);
+        }, {
+            onRetry: ({ attempt, maxAttempts, backoffMs, err }) => {
+                logger_1.logger.warn(`PixVerse uploadImage transient error — retrying`, {
+                    attempt,
+                    maxAttempts,
+                    backoffMs,
+                    message: err.message,
+                });
+            },
+        });
+    }
+    // =========================================================
     // GENERATE VIDEO
     // =========================================================
     async generateVideo(params) {
@@ -206,10 +252,17 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
             if (params.lipSync.ttsSpeakerId)
                 body.lip_sync_tts_speaker_id = params.lipSync.ttsSpeakerId;
         }
-        // I2V switches endpoint and adds the image reference.
+        // I2V switches endpoint and adds the image reference. The /img/generate
+        // endpoint does NOT accept a raw image_url — it requires an integer
+        // `img_id` from the Upload-Image API (verified 2026-06-30 against
+        // https://docs.platform.pixverse.ai/image-to-video-generation-13016633e0).
+        // Sending image_url instead surfaced in prod as ErrCode 400017 "Either
+        // img_id or api_gen_img_ids must be provided." So we upload first, then
+        // pass the returned img_id. (Distinct from the /template/generate "effect"
+        // path above, which DOES take a customer_img_url directly.)
         const isImageToVideo = !!params.inputImageUrl;
         if (isImageToVideo) {
-            body.image_url = params.inputImageUrl;
+            body.img_id = await this.uploadImage(params.inputImageUrl, traceId);
         }
         // I2V path is `/img/generate` — NOT `/image/generate`, which returns a bare
         // "404 page not found" (verified 2026-06-15 via PixVerse OpenAPI smoke test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.94",
+  "version": "1.0.95",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {