@space3-npm/cybersoul-client 1.4.11 → 1.4.13

package/dist/client.d.ts

@@ -70,6 +70,14 @@ export declare class CyberSoulClient {
      * neutral placeholder (e.g. "...") so the TTS call still has valid input.
      */
     private sanitizeTextForVoice;
+    /**
+     * Build the in-band `mediaError` envelope from the first typed media
+     * failure captured during `interact()` / `proactiveInteract()`. Keeps
+     * the conversion in one place so both call sites stay consistent and
+     * the SDK never re-throws on a partial media failure once the text
+     * reply is already in flight.
+     */
+    private buildMediaError;
     private formatHistoryEntries;
     private buildHistoryTranscript;
     interact(params: InteractParams): Promise<InteractResponse>;

package/dist/client.js

@@ -1,7 +1,7 @@
 import { InteractRequestType, } from "./types.js";
 import { robustJsonParse } from "./utils/json.utils.js";
 import { GenericLLMProvider } from "./llm.provider.js";
-import { CyberSoulApiError, CyberSoulAuthError, CyberSoulInsufficientPointsError, CyberSoulNetworkError, CyberSoulTimeoutError, CyberSoulWalletError, } from "./errors.js";
+import { CyberSoulApiError, CyberSoulAuthError, CyberSoulError, CyberSoulInsufficientPointsError, CyberSoulNetworkError, CyberSoulTimeoutError, CyberSoulWalletError, } from "./errors.js";
 export class CyberSoulClient {
     config;
     llm;
@@ -515,6 +515,35 @@ ${isProactive
             .replace(/\s+/g, " ")
             .trim();
     }
+    /**
+     * Build the in-band `mediaError` envelope from the first typed media
+     * failure captured during `interact()` / `proactiveInteract()`. Keeps
+     * the conversion in one place so both call sites stay consistent and
+     * the SDK never re-throws on a partial media failure once the text
+     * reply is already in flight.
+     */
+    buildMediaError(err, affected) {
+        if (err instanceof CyberSoulInsufficientPointsError) {
+            return {
+                kind: "insufficient-points",
+                code: err.code,
+                message: err.message,
+                affected,
+            };
+        }
+        if (err instanceof CyberSoulWalletError) {
+            return {
+                kind: "wallet",
+                message: err.message,
+                affected,
+            };
+        }
+        return {
+            kind: "unknown",
+            message: err.message,
+            affected,
+        };
+    }
     formatHistoryEntries(history, userName, agentName, promptDirective = "") {
         const contextLines = [];
         for (let i = 0; i < history.length; i++) {
@@ -712,6 +741,27 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             let finalAudioUrl = undefined;
             let finalAudioMediaId = undefined;
             let finalDurationSec = undefined;
+            // Partial-failure capture: text was already produced and emitted
+            // via [onTextReady], so a wallet / insufficient-points failure on
+            // image or voice MUST NOT abort the whole turn. We collect the
+            // affected modalities + first typed error and surface them in-band
+            // through `InteractResponse.mediaError`. The caller (MessageBus /
+            // UI) decides how to message the user without losing the reply.
+            const mediaErrorAffected = [];
+            let firstMediaError = null;
+            const captureMediaError = (modality, e) => {
+                if (!(e instanceof CyberSoulError))
+                    return;
+                if (!(e instanceof CyberSoulInsufficientPointsError) &&
+                    !(e instanceof CyberSoulWalletError)) {
+                    return;
+                }
+                if (!mediaErrorAffected.includes(modality)) {
+                    mediaErrorAffected.push(modality);
+                }
+                if (!firstMediaError)
+                    firstMediaError = e;
+            };
             // Output Event Trigger
             if (parsedIntent.triggerEvent) {
                 mediaTasks.push(this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
@@ -748,8 +798,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 })
                     .catch((e) => {
                     console.error("[CyberSoulClient] Image generation failed:", e);
-                    if (e.code === 'INSUFFICIENT_POINTS' || e.code === 'WALLET_DEDUCTION_ERROR')
-                        throw e;
+                    captureMediaError("image", e);
                 }));
             }
             const shouldGenerateVoice = types.includes(InteractRequestType.VOICE) &&
@@ -773,8 +822,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 })
                     .catch((e) => {
                     console.error("[CyberSoulClient] Voice generation failed:", e);
-                    if (e.code === 'INSUFFICIENT_POINTS' || e.code === 'WALLET_DEDUCTION_ERROR')
-                        throw e;
+                    captureMediaError("voice", e);
                 }));
             }
             // Wait for image/voice gens to return successfully
@@ -784,6 +832,9 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             // This adds at most ~1 small request to the critical path; in
             // practice the PATCH usually resolves before media generation.
             const persistedDynamicContext = (await persistedStatePromise) ?? undefined;
+            const mediaError = firstMediaError
+                ? this.buildMediaError(firstMediaError, mediaErrorAffected)
+                : undefined;
             return {
                 status: "success",
                 textResponse: resolvedTextResponse || "...",
@@ -799,9 +850,18 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 userAnalysis: parsedIntent.userAnalysis,
                 isEndTurn: parsedIntent.isEndTurn,
                 persistedDynamicContext,
+                mediaError,
             };
         }
         catch (error) {
+            // Typed SDK errors (insufficient points, wallet failure, auth, etc.)
+            // are part of the public contract — let callers branch on
+            // `instanceof` instead of string-sniffing a generic status:"error"
+            // envelope. Only truly-unexpected throws fall back to the legacy
+            // envelope so we don't break callers that don't yet handle throws.
+            if (error instanceof CyberSoulError) {
+                throw error;
+            }
             console.error("[CyberSoulClient] Interface Error: ", error);
             return {
                 status: "error",
@@ -1032,6 +1092,8 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
             }
             let finalImageUrl;
             let finalImageMediaId;
+            let proactiveMediaError = null;
+            const proactiveAffected = [];
             if (parsedIntent.imageParams) {
                 try {
                     const res = await this.generatePrimitive("image", parsedIntent.imageParams);
@@ -1040,9 +1102,17 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                 }
                 catch (e) {
                     console.error("[CyberSoulClient] Proactive Image generation failed:", e);
+                    if (e instanceof CyberSoulInsufficientPointsError ||
+                        e instanceof CyberSoulWalletError) {
+                        proactiveMediaError = e;
+                        proactiveAffected.push("image");
+                    }
                 }
             }
             const persistedDynamicContext = (await persistedStatePromise) ?? undefined;
+            const proactiveMediaErrorEnv = proactiveMediaError
+                ? this.buildMediaError(proactiveMediaError, proactiveAffected)
+                : undefined;
             return {
                 status: "success",
                 textResponse: parsedIntent.textResponse,
@@ -1051,9 +1121,14 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                 imageMediaId: finalImageMediaId,
                 stateUpdate: parsedIntent.stateUpdate,
                 persistedDynamicContext,
+                mediaError: proactiveMediaErrorEnv,
             };
         }
         catch (error) {
+            // Mirror `interact()`: preserve typed SDK errors for the caller.
+            if (error instanceof CyberSoulError) {
+                throw error;
+            }
             console.error("[CyberSoulClient] Proactive Interact Error: ", error);
             return { status: "error", error: error.message };
         }

package/dist/types.d.ts

@@ -72,6 +72,11 @@ export interface ProactiveResponse {
     stateUpdate?: DispatcherIntent["stateUpdate"];
     /** Server-authoritative post-write snapshot (see PersistedDynamicContext). */
     persistedDynamicContext?: PersistedDynamicContext;
+    /** Partial-failure descriptor: text was generated successfully but one or
+     * more media calls (image/voice) failed. Surfaced in-band so the caller
+     * can still render the text reply and explain the missing media
+     * without losing the conversation. See [InteractMediaError]. */
+    mediaError?: InteractMediaError;
     error?: string;
 }
 export interface InteractParams {
@@ -134,8 +139,30 @@ export interface InteractResponse {
     isEndTurn?: boolean;
     /** Server-authoritative post-write snapshot (see PersistedDynamicContext). */
     persistedDynamicContext?: PersistedDynamicContext;
+    /** Partial-failure descriptor: text was generated successfully but one or
+     * more media calls (image/voice) failed. Surfaced in-band so the caller
+     * can still render the text reply and explain the missing media
+     * without losing the conversation. See [InteractMediaError]. */
+    mediaError?: InteractMediaError;
     error?: string;
 }
+/**
+ * Describes a partial-failure during an [interact] / [proactiveInteract]
+ * call: the text reply was generated and returned, but image and/or
+ * voice generation failed (usually because the user ran out of points
+ * mid-turn). Surfaced in-band on the success envelope so callers can
+ * render the text response without losing it to an exception.
+ */
+export interface InteractMediaError {
+    /** Coarse kind so UIs can map to a single user-facing message. */
+    kind: "insufficient-points" | "wallet" | "unknown";
+    /** Backend machine code when available (e.g. "INSUFFICIENT_POINTS"). */
+    code?: string;
+    /** Raw error message, for logs / diagnostics. */
+    message?: string;
+    /** Which media generation calls were affected. */
+    affected: Array<"image" | "voice">;
+}
 export interface OngoingSceneState {
     scene: string;
     outfit: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.4.11",
+  "version": "1.4.13",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",