@space3-npm/cybersoul-client 1.4.15 → 1.4.16

package/dist/client.js

@@ -724,6 +724,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
@@ -799,6 +827,18 @@ 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) &&
@@ -826,6 +866,19 @@ 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) &&
@@ -1095,6 +1148,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,6 +1182,18 @@ 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 ||

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;

package/package.json

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