@space3-npm/cybersoul-client 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
-# cybersoul-client
+# @space3-npm/cybersoul-client
 
-`cybersoul-client` is the official TypeScript client SDK for interacting with the Cyber-Soul backend service. It acts as the "Brain" orchestrator on the client side, converting your local text inputs into rich, multi-modal outputs (text, voice, and image) driven by an LLM architecture.
+`@space3-npm/cybersoul-client` is the official TypeScript client SDK for interacting with the Cyber-Soul backend service. It acts as the "Brain" orchestrator on the client side, converting your local text inputs into rich, multi-modal outputs (text, voice, and image) driven by an LLM architecture.
 
 ## Overview
 
@@ -19,10 +19,10 @@ Cyber-Soul Service transforms static text-based virtual companions into fully re
 
 ## Installation
 
-You can install the SDK locally or via npm (when published):
+You can install the SDK locally or via npm:
 
 ```bash
-npm install cybersoul-client
+npm install @space3-npm/cybersoul-client
 ```
 
 ## Quick Start
@@ -30,7 +30,7 @@ npm install cybersoul-client
 Initialize the client with your Character Key (provided by your Cyber-Soul Dashboard) and your local LLM configuration:
 
 ```typescript
-import { CyberSoulClient } from 'cybersoul-client';
+import { CyberSoulClient } from '@space3-npm/cybersoul-client';
 
 const client = new CyberSoulClient({
   characterKey: 'YOUR_CHARACTER_KEY_HASH', // Ties requests to your specific Cyber-Soul persona
@@ -91,4 +91,17 @@ flowchart TD
 
 When plugging this SDK into an existing bot framework like OpenClaw, you will generally bootstrap the system once with your config files, then call `.interact()` on every new message event. 
 
-Because `interact` acts as an all-in-one state-machine adapter, it isolates multi-modal state tracking—you simply provide the raw user string and the array of recent history, and the SDK takes care of API generation, prompt construction, and relationship temperature updates implicitly.
+Because `interact` acts as an all-in-one state-machine adapter, it isolates multi-modal state tracking—you simply provide the raw user string and the array of recent history, and the SDK takes care of API generation, prompt construction, and relationship temperature updates implicitly.
+
+## API Reference
+
+The SDK perfectly mirrors the underlying Cyber-Soul backend capabilities via typed TypeScript primitives:
+
+- `getState()`: Fetches the current dynamic context, relationship stage, next events, and wardrobe metadata.
+- `updateDynamicContext(stateUpdate)`: Manually patches the character's relationship temperature or mood delta.
+- `generateImage(params)`: Synthesizes a new explicit image of the character outside of standard chat flow logic.
+- `generateVoice(params)`: Synthesizes explicit character audio (ElevenLabs/TTS) returning the URL and duration.
+- `giftOutfit(descriptionText)`: Provisions a new explicit outfit descriptor to the character's backend inventory.
+- `bootstrapCharacter(workspaceFiles)`: Automates character profile and prompt setup directly from local markdown configuration files.
+- `generateDailyScript()`: Cron-job helper instructing the AI scheduling system to compute the next block of dynamic events and plans.
+- `interact(params)`: The primary orchestrated multi-modal dialogue endpoint processing standard human <-> agent chat requests.

package/dist/client.d.ts

@@ -1,10 +1,48 @@
-import { CyberSoulClientConfig, InteractParams, InteractResponse } from "./types";
+import { CyberSoulClientConfig, InteractParams, DispatcherIntent, InteractResponse, CharacterState, ImageGenerationParams, VoiceGenerationParams } from "./types";
 export declare class CyberSoulClient {
     private config;
     private llm;
     constructor(config: CyberSoulClientConfig);
+    /**
+     * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
+     */
+    private apiFetch;
+    /**
+     * Fetches the current dynamic context and daily state.
+     */
+    getState(): Promise<CharacterState>;
+    /**
+     * Updates the character's relationship temperature or mood.
+     */
+    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"]): Promise<void>;
+    /**
+     * Manually generate an image of the character outside of chat flow.
+     */
+    generateImage(params: ImageGenerationParams): Promise<{
+        imageUrl: string;
+    }>;
+    /**
+     * Manually synthesize voice audio outside of chat flow.
+     */
+    generateVoice(params: VoiceGenerationParams): Promise<{
+        audioUrl: string;
+        durationSec?: number;
+    }>;
+    /**
+     * Gift a new outfit to the character's wardrobe inventory.
+     */
+    giftOutfit(descriptionText: string): Promise<void>;
+    /**
+     * Bootstrap character profile from OpenClaw workspace files.
+     */
+    bootstrapCharacter(workspaceFiles: Record<string, string>): Promise<void>;
+    /**
+     * Instructs the backend to generate the daily script/plan for the character.
+     * Can be triggered by local Cron systems like OpenClaw.
+     */
+    generateDailyScript(): Promise<void>;
     private fetchRemoteState;
-    private updateDynamicContext;
+    private _updateDynamicContextInternal;
     private generatePrimitive;
     interact(params: InteractParams): Promise<InteractResponse>;
 }

package/dist/client.js

@@ -13,17 +13,94 @@ export class CyberSoulClient {
             throw new Error(`Unsupported LLM provider: ${config.llmConfig.provider}`);
         }
     }
-    async fetchRemoteState() {
-        const url = `${this.config.backendUrl}/api/v1/cyber-soul/state`;
-        const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.config.characterKey}` },
+    /**
+     * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
+     */
+    async apiFetch(endpoint, options = {}) {
+        const url = `${this.config.backendUrl}${endpoint}`;
+        const headers = {
+            Authorization: `Bearer ${this.config.characterKey}`,
+            "Content-Type": "application/json",
+            ...(options.headers || {}),
+        };
+        return fetch(url, { ...options, headers });
+    }
+    /**
+     * Fetches the current dynamic context and daily state.
+     */
+    async getState() {
+        return this.fetchRemoteState();
+    }
+    /**
+     * Updates the character's relationship temperature or mood.
+     */
+    async updateDynamicContext(stateUpdate) {
+        if (!stateUpdate)
+            return;
+        // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
+        const payload = { ...stateUpdate };
+        if (payload.temperatureDelta !== undefined) {
+            payload.temperature = payload.temperatureDelta;
+            delete payload.temperatureDelta;
+        }
+        await this.apiFetch("/api/v1/cyber-soul/characters/dynamic-context", {
+            method: "PATCH",
+            body: JSON.stringify(payload),
+        }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
+    }
+    /**
+     * Manually generate an image of the character outside of chat flow.
+     */
+    async generateImage(params) {
+        return this.generatePrimitive("image", params);
+    }
+    /**
+     * Manually synthesize voice audio outside of chat flow.
+     */
+    async generateVoice(params) {
+        return this.generatePrimitive("voice", params);
+    }
+    /**
+     * Gift a new outfit to the character's wardrobe inventory.
+     */
+    async giftOutfit(descriptionText) {
+        const res = await this.apiFetch("/api/v1/cyber-soul/characters/gift-outfit", {
+            method: "POST",
+            body: JSON.stringify({ text: descriptionText }),
+        });
+        if (!res.ok)
+            throw new Error("Failed to gift outfit");
+    }
+    /**
+     * Bootstrap character profile from OpenClaw workspace files.
+     */
+    async bootstrapCharacter(workspaceFiles) {
+        const res = await this.apiFetch("/api/v1/cyber-soul/characters/bootstrap", {
+            method: "POST",
+            body: JSON.stringify({ workspace_files: workspaceFiles }),
         });
+        if (!res.ok)
+            throw new Error("Failed to bootstrap character");
+    }
+    /**
+     * Instructs the backend to generate the daily script/plan for the character.
+     * Can be triggered by local Cron systems like OpenClaw.
+     */
+    async generateDailyScript() {
+        const res = await this.apiFetch("/api/v1/cyber-soul/daily-script/generate", {
+            method: "POST",
+        });
+        if (!res.ok)
+            throw new Error("Failed to generate daily script");
+    }
+    async fetchRemoteState() {
+        const res = await this.apiFetch("/api/v1/cyber-soul/state");
         if (!res.ok)
             throw new Error("Failed to fetch character state");
         const json = await res.json();
         return json.data;
     }
-    async updateDynamicContext(stateUpdate) {
+    async _updateDynamicContextInternal(stateUpdate) {
         if (!stateUpdate)
             return;
         // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
@@ -32,24 +109,14 @@ export class CyberSoulClient {
             payload.temperature = payload.temperatureDelta;
             delete payload.temperatureDelta;
         }
-        const url = `${this.config.backendUrl}/api/v1/cyber-soul/characters/dynamic-context`;
-        await fetch(url, {
+        await this.apiFetch("/api/v1/cyber-soul/characters/dynamic-context", {
             method: "PATCH",
-            headers: {
-                Authorization: `Bearer ${this.config.characterKey}`,
-                "Content-Type": "application/json",
-            },
             body: JSON.stringify(payload),
         }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
     }
     async generatePrimitive(type, payload) {
-        const url = `${this.config.backendUrl}/api/v1/cyber-soul/${type}/generate`;
-        const res = await fetch(url, {
+        const res = await this.apiFetch(`/api/v1/cyber-soul/${type}/generate`, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.config.characterKey}`,
-                "Content-Type": "application/json",
-            },
             body: JSON.stringify(payload),
         });
         if (!res.ok)
@@ -150,8 +217,8 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             }
             console.log("[CyberSoulClient] Parsed Intent:", parsedIntent);
             // 4. Update Backend State async
-            if (parsedIntent.stateUpdate) {
-                this.updateDynamicContext(parsedIntent.stateUpdate);
+            if (parsedIntent && parsedIntent.stateUpdate) {
+                this._updateDynamicContextInternal(parsedIntent.stateUpdate);
             }
             // Fire text ready callback if provided
             if (params.onTextReady && parsedIntent.textResponse) {

package/dist/types.d.ts

@@ -39,9 +39,48 @@ export interface DispatcherIntent {
         talkingStyle?: string;
     };
 }
+export interface CharacterState {
+    current_time: string;
+    active_event?: any;
+    next_event?: any;
+    active_wardrobe?: any;
+    active_story_arcs?: string[];
+    dynamic_context?: any;
+    relationship_stage?: string;
+    name?: string;
+    age?: number;
+    gender?: string;
+    occupation?: string;
+    personality_traits?: string;
+    interaction_boundaries?: string;
+    communication_style?: string;
+}
 export interface BaseLLMProvider {
     generate(messages: {
         role: string;
         content: string;
     }[], maxTokens?: number, temperature?: number): Promise<string>;
 }
+export interface ImageGenerationParams {
+    mode: 'structured' | 'full-prompt';
+    full_prompt?: string;
+    expression?: string;
+    condition?: string;
+    pose?: string;
+    view_angle?: string;
+    exposure?: string;
+    outfit?: string;
+    scene?: string;
+    ondemandOutfit?: string;
+    style?: string;
+    triggerWord?: string;
+    appearanceBody?: string;
+    appearanceFace?: string;
+}
+export interface VoiceGenerationParams {
+    text: string;
+    dynamicArgs: {
+        style_instruction?: string;
+        emotion?: string;
+    };
+}

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.0.0",
-  "type": "module", "main": "dist/index.js", "module": "dist/index.js",
+  "version": "1.0.2",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"