@space3-npm/cybersoul-client 1.4.15 → 1.4.17

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, CyberSoulError, CyberSoulInsufficientPointsError, CyberSoulNetworkError, CyberSoulTimeoutError, CyberSoulWalletError, } from "./errors.js";
+import { CyberSoulApiError, CyberSoulAuthError, CyberSoulError, CyberSoulInsufficientPointsError, CyberSoulNetworkError, CyberSoulSensitiveContentError, CyberSoulTimeoutError, CyberSoulWalletError, } from "./errors.js";
 export class CyberSoulClient {
     config;
     llm;
@@ -146,6 +146,9 @@ export class CyberSoulClient {
             if (code === "WALLET_DEDUCTION_ERROR") {
                 throw new CyberSoulWalletError(endpoint, "POST", res.status, detailedMessage, errData, code);
             }
+            if (code === "E005") {
+                throw new CyberSoulSensitiveContentError(endpoint, "POST", res.status, detailedMessage, errData, code);
+            }
             if (res.status === 401 || res.status === 403) {
                 throw new CyberSoulAuthError(endpoint, "POST", res.status, detailedMessage, errData);
             }
@@ -542,6 +545,14 @@ ${isProactive
                 affected,
             };
         }
+        if (err instanceof CyberSoulSensitiveContentError) {
+            return {
+                kind: "sensitive-content",
+                code: err.code,
+                message: err.message,
+                affected,
+            };
+        }
         return {
             kind: "unknown",
             message: err.message,
@@ -724,6 +735,34 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             if (parsedIntent && (parsedIntent.stateUpdate || parsedIntent.userAnalysis)) {
                 persistedStatePromise = this._updateDynamicContextInternal(parsedIntent.stateUpdate, parsedIntent.userAnalysis);
             }
+            // Fire `onStateReady` the moment the dynamic-context PATCH resolves
+            // (or immediately, when no state update was emitted). This is
+            // independent of media generation, so the UI can stop showing
+            // "updating…" on temperature / relationship stage well before the
+            // (potentially slow) image task finishes. Errors are swallowed:
+            // an authoritative snapshot is best-effort, the optimistic delta
+            // already applied client-side is the fallback.
+            if (params.onStateReady) {
+                const stateReadyCb = params.onStateReady;
+                persistedStatePromise
+                    .then((persisted) => {
+                    try {
+                        stateReadyCb(persisted ?? {});
+                    }
+                    catch (cbErr) {
+                        console.warn("[CyberSoulClient] onStateReady callback threw:", cbErr);
+                    }
+                })
+                    .catch(() => {
+                    // PATCH failed; still signal LLM-phase complete with an empty snapshot.
+                    try {
+                        stateReadyCb({});
+                    }
+                    catch (cbErr) {
+                        console.warn("[CyberSoulClient] onStateReady callback threw:", cbErr);
+                    }
+                });
+            }
             const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
                 parsedIntent.textResponse.trim().length > 0
                 ? parsedIntent.textResponse
@@ -757,7 +796,8 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 if (!(e instanceof CyberSoulError))
                     return;
                 if (!(e instanceof CyberSoulInsufficientPointsError) &&
-                    !(e instanceof CyberSoulWalletError)) {
+                    !(e instanceof CyberSoulWalletError) &&
+                    !(e instanceof CyberSoulSensitiveContentError)) {
                     return;
                 }
                 if (!mediaErrorAffected.includes(modality)) {
@@ -799,10 +839,23 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                     .then((res) => {
                     finalImageUrl = res.image_url;
                     finalImageMediaId = res.id;
+                    if (params.onMediaReady && finalImageUrl) {
+                        try {
+                            params.onMediaReady({
+                                modality: "image",
+                                url: finalImageUrl,
+                                mediaId: finalImageMediaId,
+                            });
+                        }
+                        catch (cbErr) {
+                            console.warn("[CyberSoulClient] onMediaReady(image) threw:", cbErr);
+                        }
+                    }
                 })
                     .catch((e) => {
                     if (!(e instanceof CyberSoulInsufficientPointsError) &&
-                        !(e instanceof CyberSoulWalletError)) {
+                        !(e instanceof CyberSoulWalletError) &&
+                        !(e instanceof CyberSoulSensitiveContentError)) {
                         console.error("[CyberSoulClient] Image generation failed:", e);
                     }
                     captureMediaError("image", e);
@@ -826,10 +879,24 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                     finalAudioUrl = res.audio_url;
                     finalAudioMediaId = res.id;
                     finalDurationSec = res.duration_sec;
+                    if (params.onMediaReady && finalAudioUrl) {
+                        try {
+                            params.onMediaReady({
+                                modality: "voice",
+                                url: finalAudioUrl,
+                                mediaId: finalAudioMediaId,
+                                durationSec: finalDurationSec,
+                            });
+                        }
+                        catch (cbErr) {
+                            console.warn("[CyberSoulClient] onMediaReady(voice) threw:", cbErr);
+                        }
+                    }
                 })
                     .catch((e) => {
                     if (!(e instanceof CyberSoulInsufficientPointsError) &&
-                        !(e instanceof CyberSoulWalletError)) {
+                        !(e instanceof CyberSoulWalletError) &&
+                        !(e instanceof CyberSoulSensitiveContentError)) {
                         console.error("[CyberSoulClient] Voice generation failed:", e);
                     }
                     captureMediaError("voice", e);
@@ -1095,6 +1162,26 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
             if (parsedIntent.stateUpdate) {
                 persistedStatePromise = this._updateDynamicContextInternal(parsedIntent.stateUpdate);
             }
+            if (params.onStateReady) {
+                const stateReadyCb = params.onStateReady;
+                persistedStatePromise
+                    .then((persisted) => {
+                    try {
+                        stateReadyCb(persisted ?? {});
+                    }
+                    catch (cbErr) {
+                        console.warn("[CyberSoulClient] onStateReady callback threw:", cbErr);
+                    }
+                })
+                    .catch(() => {
+                    try {
+                        stateReadyCb({});
+                    }
+                    catch (cbErr) {
+                        console.warn("[CyberSoulClient] onStateReady callback threw:", cbErr);
+                    }
+                });
+            }
             if (params.onTextReady) {
                 params.onTextReady(parsedIntent.textResponse, parsedIntent.actionText, {
                     stateUpdate: parsedIntent.stateUpdate,
@@ -1109,10 +1196,23 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                     const res = await this.generatePrimitive("image", parsedIntent.imageParams);
                     finalImageUrl = res.image_url;
                     finalImageMediaId = res.id;
+                    if (params.onMediaReady && finalImageUrl) {
+                        try {
+                            params.onMediaReady({
+                                modality: "image",
+                                url: finalImageUrl,
+                                mediaId: finalImageMediaId,
+                            });
+                        }
+                        catch (cbErr) {
+                            console.warn("[CyberSoulClient] onMediaReady(image) threw:", cbErr);
+                        }
+                    }
                 }
                 catch (e) {
                     if (e instanceof CyberSoulInsufficientPointsError ||
-                        e instanceof CyberSoulWalletError) {
+                        e instanceof CyberSoulWalletError ||
+                        e instanceof CyberSoulSensitiveContentError) {
                         proactiveMediaError = e;
                         proactiveAffected.push("image");
                     }

package/dist/errors.d.ts

@@ -80,3 +80,13 @@ export declare class CyberSoulWalletError extends CyberSoulApiError {
     readonly code: string;
     constructor(endpoint: string, method: string, status: number, message: string, body?: unknown, code?: string);
 }
+/**
+ * The backend rejected an image/voice generation request because the
+ * prompt (or the model's output) was flagged as sensitive / unsafe
+ * (backend code `E005`). The user can recover by sending a different
+ * prompt — there's nothing to retry automatically.
+ */
+export declare class CyberSoulSensitiveContentError extends CyberSoulApiError {
+    readonly code: string;
+    constructor(endpoint: string, method: string, status: number, message: string, body?: unknown, code?: string);
+}

package/dist/errors.js

@@ -108,3 +108,16 @@ export class CyberSoulWalletError extends CyberSoulApiError {
         this.code = code;
     }
 }
+/**
+ * The backend rejected an image/voice generation request because the
+ * prompt (or the model's output) was flagged as sensitive / unsafe
+ * (backend code `E005`). The user can recover by sending a different
+ * prompt — there's nothing to retry automatically.
+ */
+export class CyberSoulSensitiveContentError extends CyberSoulApiError {
+    code;
+    constructor(endpoint, method, status, message, body, code = "E005") {
+        super(endpoint, method, status, message, body, "sensitive-content");
+        this.code = code;
+    }
+}

package/dist/types.d.ts

@@ -53,12 +53,37 @@ export interface PersistedDynamicContext {
     /** Persisted relationship stage label after re-evaluation. */
     relationshipStage?: string;
 }
+/**
+ * Payload delivered by [InteractParams.onMediaReady] when an individual
+ * media task (image/voice) finishes. Fires from inside the SDK's
+ * per-modality `.then()` so callers can render the bubble the moment
+ * that modality is ready, instead of waiting for the slowest one to
+ * finish. The aggregated `InteractResponse` is still returned at the
+ * end and carries the same URLs (no double-render needed if the caller
+ * tracks per-modality state).
+ */
+export interface MediaReadyPayload {
+    modality: "image" | "voice";
+    url: string;
+    mediaId?: string;
+    /** Voice only — TTS duration in seconds when known. */
+    durationSec?: number;
+}
 export interface ProactiveParams {
     history?: HistoryEntry[];
     maxUnreplied?: number;
     requestTypes?: InteractRequestType[];
     localContext?: string;
     onTextReady?: (textResponse: string, actionText?: string, metadata?: InteractMetadata) => void;
+    /**
+     * Fires when the server-authoritative PATCH /dynamic-context resolves,
+     * before media generation completes. Lets the UI update the live
+     * temperature / relationship stage immediately instead of waiting for
+     * the (potentially slow) image task.
+     */
+    onStateReady?: (persisted: PersistedDynamicContext) => void;
+    /** Fires per modality as each media task settles successfully. */
+    onMediaReady?: (payload: MediaReadyPayload) => void;
 }
 export interface ProactiveResponse {
     status: "success" | "skipped" | "error";
@@ -85,6 +110,17 @@ export interface InteractParams {
     requestTypes?: InteractRequestType[];
     history?: HistoryEntry[];
     onTextReady?: (textResponse: string, actionText?: string, metadata?: InteractMetadata) => void;
+    /**
+     * Fires when the server-authoritative PATCH /dynamic-context resolves,
+     * before media generation completes. Lets the UI update the live
+     * temperature / relationship stage immediately instead of waiting for
+     * the (potentially slow) image task. When the turn has no
+     * `stateUpdate`, this still fires with an empty object so callers can
+     * use it as a generic "LLM phase done" signal.
+     */
+    onStateReady?: (persisted: PersistedDynamicContext) => void;
+    /** Fires per modality as each media task settles successfully. */
+    onMediaReady?: (payload: MediaReadyPayload) => void;
 }
 export interface OndemandEventParams {
     eventDescription: string;
@@ -155,7 +191,7 @@ export interface InteractResponse {
  */
 export interface InteractMediaError {
     /** Coarse kind so UIs can map to a single user-facing message. */
-    kind: "insufficient-points" | "wallet" | "unknown";
+    kind: "insufficient-points" | "wallet" | "sensitive-content" | "unknown";
     /** Backend machine code when available (e.g. "INSUFFICIENT_POINTS"). */
     code?: string;
     /** Raw error message, for logs / diagnostics. */

package/package.json

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