@spawnco/sdk-types 0.0.47 → 0.0.49

package/dist/index.d.mts

@@ -213,6 +213,30 @@ interface SpawnServerSDK__V1<TConfig = any> {
             price: number;
         }): Promise<boolean>;
     };
+    /**
+     * Variant-scoped document storage.
+     * Documents persist across server restarts and copy when variants fork.
+     */
+    documents: {
+        /**
+         * Read a document by name. Returns null if not found.
+         * Documents are scoped to the current variant.
+         */
+        get<T = unknown>(name: string): Promise<T | null>;
+        /**
+         * Write a document. Creates if not exists, replaces if exists.
+         * Value must be JSON-serializable.
+         */
+        set<T = unknown>(name: string, value: T): Promise<void>;
+        /**
+         * Delete a document by name.
+         */
+        delete(name: string): Promise<void>;
+        /**
+         * List all document names for this variant.
+         */
+        list(): Promise<string[]>;
+    };
     config: {
         get(): Promise<TConfig>;
         version(): Promise<string>;
@@ -292,6 +316,48 @@ interface SpawnServerSDK__V1<TConfig = any> {
             limit?: number;
         }): Promise<Record<string, LeaderboardEntry[]>>;
     };
+    /**
+     * LLM API for conversational AI with persistent memory.
+     * Used for NPC dialog, content generation, and dynamic gameplay.
+     */
+    llm: LlmApi;
+}
+type LlmModel = 'fast' | 'smart';
+interface LlmChatOptions<T = void> {
+    /** Unique conversation ID, e.g., "npc:merlin:player:123" */
+    conversationId: string;
+    /** User's message to the AI */
+    message: string;
+    /** System prompt (only used on first message of conversation) */
+    system?: string;
+    /** JSON Schema for structured output (uses tool_use under the hood) */
+    schema?: T extends void ? never : object;
+    /** Max messages to keep in history (default: 20) */
+    maxHistory?: number;
+    /** Model selection: 'fast' (~500ms) or 'smart' (~2s) */
+    model?: LlmModel;
+}
+interface LlmChatResponse<T = void> {
+    /** Raw response text */
+    text: string;
+    /** Parsed object if schema was provided */
+    object: T extends void ? undefined : T;
+    /** Token usage for billing */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface LlmApi {
+    /**
+     * Conversational chat with persistent memory.
+     * Conversation state stored in variant documents automatically.
+     */
+    chat<T = void>(options: LlmChatOptions<T>): Promise<LlmChatResponse<T>>;
+    /**
+     * Clear conversation history (e.g., NPC "forgets" player)
+     */
+    clearConversation(conversationId: string): Promise<void>;
 }
 interface TokenPayload {
     sub: string;
@@ -356,6 +422,6 @@ interface LeaderboardEntry {
     timestamp: number;
 }
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy'>;
-type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room'>;
+type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room' | 'llm'>;
 
-export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, LeaderboardEntry, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };
+export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };

package/dist/index.d.ts

@@ -213,6 +213,30 @@ interface SpawnServerSDK__V1<TConfig = any> {
             price: number;
         }): Promise<boolean>;
     };
+    /**
+     * Variant-scoped document storage.
+     * Documents persist across server restarts and copy when variants fork.
+     */
+    documents: {
+        /**
+         * Read a document by name. Returns null if not found.
+         * Documents are scoped to the current variant.
+         */
+        get<T = unknown>(name: string): Promise<T | null>;
+        /**
+         * Write a document. Creates if not exists, replaces if exists.
+         * Value must be JSON-serializable.
+         */
+        set<T = unknown>(name: string, value: T): Promise<void>;
+        /**
+         * Delete a document by name.
+         */
+        delete(name: string): Promise<void>;
+        /**
+         * List all document names for this variant.
+         */
+        list(): Promise<string[]>;
+    };
     config: {
         get(): Promise<TConfig>;
         version(): Promise<string>;
@@ -292,6 +316,48 @@ interface SpawnServerSDK__V1<TConfig = any> {
             limit?: number;
         }): Promise<Record<string, LeaderboardEntry[]>>;
     };
+    /**
+     * LLM API for conversational AI with persistent memory.
+     * Used for NPC dialog, content generation, and dynamic gameplay.
+     */
+    llm: LlmApi;
+}
+type LlmModel = 'fast' | 'smart';
+interface LlmChatOptions<T = void> {
+    /** Unique conversation ID, e.g., "npc:merlin:player:123" */
+    conversationId: string;
+    /** User's message to the AI */
+    message: string;
+    /** System prompt (only used on first message of conversation) */
+    system?: string;
+    /** JSON Schema for structured output (uses tool_use under the hood) */
+    schema?: T extends void ? never : object;
+    /** Max messages to keep in history (default: 20) */
+    maxHistory?: number;
+    /** Model selection: 'fast' (~500ms) or 'smart' (~2s) */
+    model?: LlmModel;
+}
+interface LlmChatResponse<T = void> {
+    /** Raw response text */
+    text: string;
+    /** Parsed object if schema was provided */
+    object: T extends void ? undefined : T;
+    /** Token usage for billing */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface LlmApi {
+    /**
+     * Conversational chat with persistent memory.
+     * Conversation state stored in variant documents automatically.
+     */
+    chat<T = void>(options: LlmChatOptions<T>): Promise<LlmChatResponse<T>>;
+    /**
+     * Clear conversation history (e.g., NPC "forgets" player)
+     */
+    clearConversation(conversationId: string): Promise<void>;
 }
 interface TokenPayload {
     sub: string;
@@ -356,6 +422,6 @@ interface LeaderboardEntry {
     timestamp: number;
 }
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy'>;
-type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room'>;
+type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room' | 'llm'>;
 
-export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, LeaderboardEntry, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };
+export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spawnco/sdk-types",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "description": "TypeScript type definitions for Spawn SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/v1.ts

@@ -234,6 +234,34 @@ export interface SpawnServerSDK__V1<TConfig = any> {
     verifyPurchase({ purchaseId, price }: { purchaseId: string; price: number }): Promise<boolean>;
   };
 
+  /**
+   * Variant-scoped document storage.
+   * Documents persist across server restarts and copy when variants fork.
+   */
+  documents: {
+    /**
+     * Read a document by name. Returns null if not found.
+     * Documents are scoped to the current variant.
+     */
+    get<T = unknown>(name: string): Promise<T | null>;
+
+    /**
+     * Write a document. Creates if not exists, replaces if exists.
+     * Value must be JSON-serializable.
+     */
+    set<T = unknown>(name: string, value: T): Promise<void>;
+
+    /**
+     * Delete a document by name.
+     */
+    delete(name: string): Promise<void>;
+
+    /**
+     * List all document names for this variant.
+     */
+    list(): Promise<string[]>;
+  };
+
   config: {
     get(): Promise<TConfig>;
     version(): Promise<string>;
@@ -351,6 +379,55 @@ export interface SpawnServerSDK__V1<TConfig = any> {
       }
     ): Promise<Record<string, LeaderboardEntry[]>>;
   };
+
+  /**
+   * LLM API for conversational AI with persistent memory.
+   * Used for NPC dialog, content generation, and dynamic gameplay.
+   */
+  llm: LlmApi;
+}
+
+// LLM Types
+export type LlmModel = 'fast' | 'smart';
+
+export interface LlmChatOptions<T = void> {
+  /** Unique conversation ID, e.g., "npc:merlin:player:123" */
+  conversationId: string;
+  /** User's message to the AI */
+  message: string;
+  /** System prompt (only used on first message of conversation) */
+  system?: string;
+  /** JSON Schema for structured output (uses tool_use under the hood) */
+  schema?: T extends void ? never : object;
+  /** Max messages to keep in history (default: 20) */
+  maxHistory?: number;
+  /** Model selection: 'fast' (~500ms) or 'smart' (~2s) */
+  model?: LlmModel;
+}
+
+export interface LlmChatResponse<T = void> {
+  /** Raw response text */
+  text: string;
+  /** Parsed object if schema was provided */
+  object: T extends void ? undefined : T;
+  /** Token usage for billing */
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+}
+
+export interface LlmApi {
+  /**
+   * Conversational chat with persistent memory.
+   * Conversation state stored in variant documents automatically.
+   */
+  chat<T = void>(options: LlmChatOptions<T>): Promise<LlmChatResponse<T>>;
+
+  /**
+   * Clear conversation history (e.g., NPC "forgets" player)
+   */
+  clearConversation(conversationId: string): Promise<void>;
 }
 
 // Token types
@@ -422,4 +499,4 @@ export interface LeaderboardEntry {
 // v0 sdk types for testing
 
 export type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy'>;
-export type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room'>;
+export type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room' | 'llm'>;