@storvia/sdk 0.2.2 → 0.3.1

package/dist/index.d.mts

@@ -20,7 +20,7 @@ type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_BALANCE' | 'RATE_LIMITED'
 interface ChatSendOptions {
     message: string;
     topic?: string;
-    context?: string;
+    scene_key?: string;
     stream?: boolean;
     onChunk?: (text: string) => void;
     onDone?: (id: string) => void;
@@ -32,7 +32,7 @@ interface ChatSaveOptions {
 }
 interface ChatGenerateOptions {
     topic?: string;
-    context?: string;
+    scene_key?: string;
     stream?: boolean;
     save?: boolean;
     onChunk?: (text: string) => void;
@@ -40,7 +40,7 @@ interface ChatGenerateOptions {
 }
 interface ChatRetryOptions {
     topic?: string;
-    context?: string;
+    scene_key?: string;
     stream?: boolean;
     onChunk?: (text: string) => void;
     onDone?: (id: string) => void;
@@ -162,7 +162,7 @@ declare class ChatModule {
         id: string;
     }>;
     /**
-     * 基于 topic 历史 + context 请求 AI 生成回复（无需当前轮用户输入）
+     * 基于 topic 历史 + scene_key 请求 AI 生成回复（无需当前轮用户输入）
      * 适用于群聊 NPC 回复、NPC 自动发言、弹幕生成等
      */
     generate(options: ChatGenerateOptions): Promise<ChatResponse | void>;
@@ -171,7 +171,10 @@ declare class ChatModule {
      * 适用于 AI 回复出错或不满意时重新生成
      */
     retry(options?: ChatRetryOptions): Promise<ChatResponse | void>;
-    /** 预览模式：发到 /preview 端点 */
+    /** 预览模式：发到 /preview 端点
+     *  - 创作台预览：父页面已注入 previewConfig，请求体塞 prompt_config，服务端不查库
+     *  - 本地预览 / dev：无 previewConfig，请求体塞 game_id，服务端按 hash_id 查 prompts
+     */
     private sendPreview;
 }
 
@@ -179,8 +182,11 @@ declare class CharacterStateModule {
     private http;
     private getConversationId;
     private isPreview;
+    /** characterName → state（与正式模式 GET /characters/:name/state 同结构） */
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialStates?: Record<string, Record<string, FieldValue>>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialStates: Record<string, Record<string, FieldValue>> | undefined): void;
     get(characterName: string): Promise<Record<string, FieldValue>>;
     update(characterName: string, values: Record<string, string | number | boolean>): Promise<void>;
 }
@@ -190,7 +196,9 @@ declare class CharactersModule {
     private isPreview;
     state: CharacterStateModule;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialCharacters?: CharacterPersona[], initialStates?: Record<string, Record<string, FieldValue>>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialCharacters: CharacterPersona[] | undefined, initialStates: Record<string, Record<string, FieldValue>> | undefined): void;
     list(): Promise<CharacterPersona[]>;
     get(name: string): Promise<CharacterPersona>;
     add(character: CharacterAddOptions): Promise<void>;
@@ -212,7 +220,9 @@ declare class RelationshipsModule {
     private getConversationId;
     private isPreview;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialRelationships?: Relationship[]);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialRelationships: Relationship[] | undefined): void;
     list(): Promise<Relationship[]>;
     get(from: string, to: string): Promise<Relationship>;
     add(relationship: Relationship): Promise<void>;
@@ -230,7 +240,9 @@ declare class InventoryModule {
     private getConversationId;
     private isPreview;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialInventory?: InventoryState);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialInventory: InventoryState | undefined): void;
     /** 返回整个物品栏（分组 → 物品名 → 数据） */
     list(): Promise<InventoryState>;
     /** 返回指定分组下的物品（物品名 → 数据） */
@@ -254,7 +266,9 @@ declare class WorldModule {
     private getConversationId;
     private isPreview;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialWorld?: Record<string, unknown>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialWorld: Record<string, unknown> | undefined): void;
     get(): Promise<Record<string, unknown>>;
     update(data: Record<string, unknown>): Promise<void>;
 }
@@ -264,7 +278,9 @@ declare class PlayerStateModule {
     private getConversationId;
     private isPreview;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialState?: Record<string, Record<string, FieldValue>>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialState: Record<string, Record<string, FieldValue>> | undefined): void;
     get(): Promise<Record<string, Record<string, FieldValue>>>;
     get(group: string): Promise<Record<string, FieldValue>>;
     update(group: string, values: Record<string, string | number | boolean>): Promise<void>;
@@ -275,7 +291,9 @@ declare class PlayerModule {
     private isPreview;
     state: PlayerStateModule;
     private memPersona;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialPersona?: PlayerPersona, initialState?: Record<string, Record<string, FieldValue>>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialPersona: PlayerPersona | undefined, initialState: Record<string, Record<string, FieldValue>> | undefined): void;
     get(): Promise<PlayerPersona>;
     update(data: Partial<PlayerPersona>): Promise<void>;
 }
@@ -285,7 +303,9 @@ declare class CustomModule {
     private getConversationId;
     private isPreview;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialCustom?: Record<string, unknown>);
+    /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
+    setInitial(initialCustom: Record<string, unknown> | undefined): void;
     get(): Promise<Record<string, unknown>>;
     get(key: string): Promise<unknown>;
     set(data: Record<string, unknown>): Promise<void>;
@@ -319,6 +339,15 @@ declare class StorviaSDK {
     init(): Promise<void>;
     /** 监听父页面 postMessage（预览模式） */
     private listenForPreviewMessages;
+    /**
+     * 调用 POST /preview/initial-snapshot 拉取与正式发布等价的初始数据
+     * - 预览模式：传 game_config + game_state_override（来自 previewConfig）
+     * - dev 模式：HttpClient 自动带 x-api-key，后端按 game_id 反查
+     * 失败时返回 null（不阻塞 init，list/get 仍能用空 mem 工作）
+     */
+    private fetchPreviewSnapshot;
+    /** 重新拉 snapshot 并把结果灌进每个 module 的 mem（用于 update-config 后同步） */
+    private refreshPreviewSnapshot;
     /** 保存设置到后端 */
     private saveSettings;
     /** 同步最新游戏设定到当前存档 */