@kokimoki/app 2.0.0 → 2.0.1

package/dist/llms.txt

@@ -1,8 +1,3 @@
----
-description: Instructions for the Kokimoki SDK
-applyTo: '**/*.tsx,**/*.ts'
----
-
 # Kokimoki SDK
 
 The Kokimoki SDK is a comprehensive development toolkit for building real-time collaborative game applications
@@ -51,7 +46,7 @@ Kokimoki Store powered by `valtio` and `valtio-yjs` for real-time state manageme
 **Example: Creating a Store**
 
 ```typescript
-import { kmClient } from '@services/km-client';
+import { kmClient } from "@services/km-client";
 
 interface State {
   title: string;
@@ -59,12 +54,12 @@ interface State {
 }
 
 const initialState: State = {
-  title: 'Store',
-  count: 0
+  title: "Store",
+  count: 0,
 };
 
 // Initialize global store with initial state
-export const store = kmClient.store<PlayerState>('store-name', initialState);
+export const store = kmClient.store<PlayerState>("store-name", initialState);
 ```
 
 ### State management
@@ -79,11 +74,11 @@ export const store = kmClient.store<PlayerState>('store-name', initialState);
 **Example: Updating State**
 
 ```typescript
-import { store } from '../store';
+import { store } from "../store";
 
 // Update state
 await kmClient.transact([store], ([state]) => {
-  state.title = 'New store';
+  state.title = "New store";
   state.count += 1;
 });
 ```
@@ -98,8 +93,8 @@ await kmClient.transact([store], ([state]) => {
 ```typescript
 // Update multiple stores in a single transaction
 await kmClient.transact([store1, store2], ([state1, state2]) => {
-  state1.name = 'My Store1';
-  state2.name = 'My Store2';
+  state1.name = "My Store1";
+  state2.name = "My Store2";
 });
 ```
 
@@ -111,8 +106,8 @@ await kmClient.transact([store1, store2], ([state1, state2]) => {
 **Example: Using State in Components**
 
 ```tsx
-import { useSnapshot } from 'valtio';
-import { store } from '../store';
+import { useSnapshot } from "valtio";
+import { store } from "../store";
 
 const Component = () => {
   // Get reactive snapshot of the store state
@@ -156,9 +151,9 @@ Uploads a file to storage.
 **Example:**
 
 ```typescript
-const upload: Upload = await kmClient.storage.upload('filename.jpg', fileBlob, [
-  'tag1',
-  'tag2'
+const upload: Upload = await kmClient.storage.upload("filename.jpg", fileBlob, [
+  "tag1",
+  "tag2",
 ]);
 // Use upload.url to access the media file
 ```
@@ -180,7 +175,7 @@ Query uploaded files by filter and pagination
 ```typescript
 // Query uploads by tag and uploaded by this client
 const { items, total } = await kmClient.storage.listUploads(
-  { clientId: kmClient.id, tags: ['tag1'] },
+  { clientId: kmClient.id, tags: ["tag1"] },
   skip,
   limit
 );
@@ -199,7 +194,7 @@ Replace uploaded file tags with new tags
 
 ```typescript
 const updatedUpload: Upload = await kmClient.storage.updateUpload(upload.id, {
-  tags: ['new']
+  tags: ["new"],
 });
 ```
 
@@ -245,7 +240,9 @@ interface Paginated<T> {
 
 ```typescript
 // Get uploaded files by clientId
-const clientUploads = await kmClient.storage.listUploads({ clientId: kmClient.id });
+const clientUploads = await kmClient.storage.listUploads({
+  clientId: kmClient.id,
+});
 ```
 
 #### Example: Filter by file type
@@ -253,7 +250,7 @@ const clientUploads = await kmClient.storage.listUploads({ clientId: kmClient.id
 ```typescript
 // Get only uploaded images
 const images = await kmClient.storage.listUploads({
-  mimeTypes: ['image/jpeg', 'image/png']
+  mimeTypes: ["image/jpeg", "image/png"],
 });
 ```
 
@@ -261,17 +258,19 @@ const images = await kmClient.storage.listUploads({
 
 ```typescript
 // Upload file with tag
-await kmClient.storage.upload('avatar.jpg', blob, ['profile']);
+await kmClient.storage.upload("avatar.jpg", blob, ["profile"]);
 
 // Query uploads by tag
-const profileUploads = await kmClient.storage.listUploads({ tags: ['profile'] });
+const profileUploads = await kmClient.storage.listUploads({
+  tags: ["profile"],
+});
 ```
 
 #### Example: Usage in Kokimoki Store
 
 ```typescript
 // Upload image from Blob
-const upload = await kmClient.storage.upload('file.jpg', blob);
+const upload = await kmClient.storage.upload("file.jpg", blob);
 
 await kmClient.transact([store], (state) => {
   // Add image to images array in the store
@@ -319,11 +318,11 @@ Used to generate text response with AI
 ```typescript
 // Generate text response
 const { content } = await kmClient.ai.chat({
-  model: 'gemini-2.5-flash-lite',
-  systemPrompt: 'You are a sarcastic assistant',
-  userPrompt: 'Write a story about dragons',
+  model: "gemini-2.5-flash-lite",
+  systemPrompt: "You are a sarcastic assistant",
+  userPrompt: "Write a story about dragons",
   temperature: 0.7, // moderate creativity
-  maxTokens: 500 // limit to 500 tokens
+  maxTokens: 500, // limit to 500 tokens
 });
 ```
 
@@ -359,13 +358,13 @@ interface Question {
 }
 
 const questions = await kmClient.ai.generateJson<Question[]>({
-  systemPrompt: 'Generate quiz questions as JSON array',
-  userPrompt: 'Create 5 history quiz questions with 4 options each',
-  temperature: 0.7
+  systemPrompt: "Generate quiz questions as JSON array",
+  userPrompt: "Create 5 history quiz questions with 4 options each",
+  temperature: 0.7,
 });
 
 // questions is already parsed and typed
-questions.forEach(q => console.log(q.question));
+questions.forEach((q) => console.log(q.question));
 ```
 
 ```typescript
@@ -378,8 +377,8 @@ interface Character {
 }
 
 const character = await kmClient.ai.generateJson<Character>({
-  userPrompt: 'Create a fantasy warrior character with stats',
-  temperature: 0.8
+  userPrompt: "Create a fantasy warrior character with stats",
+  temperature: 0.8,
 });
 
 console.log(character.name, character.strength);
@@ -400,9 +399,9 @@ Used to modify/transform image with AI. The result is stored as [`Upload`](#stor
 ```typescript
 // Modify image from url
 const upload: Upload = await kmClient.ai.modifyImage(
-  'https://static.kokimoki.com/game/image.jpg',
-  'Make it look like a painting',
-  ['art', 'ai-generated']
+  "https://static.kokimoki.com/game/image.jpg",
+  "Make it look like a painting",
+  ["art", "ai-generated"]
 );
 ```
 
@@ -420,8 +419,8 @@ Each Kokimoki store has a `connections` property that provides real-time presenc
 ### Example: Track Online Players
 
 ```tsx
-import { useSnapshot } from 'valtio';
-import { globalStore } from '@/state/stores/global-store';
+import { useSnapshot } from "valtio";
+import { globalStore } from "@/state/stores/global-store";
 
 const Component = () => {
   // Get online client IDs from store connections
@@ -440,8 +439,8 @@ const Component = () => {
 ### Example: Display Player List with Online Status
 
 ```tsx
-import { useSnapshot } from 'valtio';
-import { globalStore } from '@/state/stores/global-store';
+import { useSnapshot } from "valtio";
+import { globalStore } from "@/state/stores/global-store";
 
 const PlayerList = () => {
   const players = useSnapshot(globalStore.proxy).players;
@@ -451,14 +450,14 @@ const PlayerList = () => {
     clientId,
     name: player.name,
 
-    isOnline: onlineClientIds.has(clientId)
+    isOnline: onlineClientIds.has(clientId),
   }));
 
   return (
     <ul>
       {playersList.map((player) => (
         <li key={player.clientId}>
-          {player.name} - {player.isOnline ? 'Online' : 'Offline'}
+          {player.name} - {player.isOnline ? "Online" : "Offline"}
         </li>
       ))}
     </ul>
@@ -483,12 +482,14 @@ Access leaderboard API via `kmClient.leaderboard`.
 ### When to Use Leaderboard API vs Global Store
 
 **Use the Leaderboard API when:**
+
 - You have a large number of entries (hundreds to thousands of players)
 - You need efficient ranking and sorting with database indexes
 - You want pagination and optimized queries for top scores
 - Memory and network efficiency are important
 
 **Use a Global Store when:**
+
 - You have a small number of players (typically under 100)
 - You need real-time updates and live leaderboard changes
 - You want to combine player scores with other game state
@@ -516,11 +517,11 @@ Add a new entry to a leaderboard. Creates a new entry each time it's called.
 
 ```typescript
 const { rank } = await kmClient.leaderboard.insertEntry(
-  'high-scores',
-  'desc',
+  "high-scores",
+  "desc",
   1500,
-  { playerName: 'Alice', level: 10 },
-  { sessionId: 'abc123' }
+  { playerName: "Alice", level: 10 },
+  { sessionId: "abc123" }
 );
 console.log(`New rank: ${rank}`);
 ```
@@ -543,11 +544,11 @@ Add or update the latest entry for the current client in a leaderboard. Replaces
 
 ```typescript
 const { rank } = await kmClient.leaderboard.upsertEntry(
-  'daily-scores',
-  'desc',
+  "daily-scores",
+  "desc",
   2000,
-  { playerName: 'Bob', completionTime: 120 },
-  { deviceId: 'xyz789' }
+  { playerName: "Bob", completionTime: 120 },
+  { deviceId: "xyz789" }
 );
 console.log(`Updated rank: ${rank}`);
 ```
@@ -569,14 +570,16 @@ List entries in a leaderboard with pagination.
 
 ```typescript
 const { items, total } = await kmClient.leaderboard.listEntries(
-  'weekly-scores',
-  'desc',
+  "weekly-scores",
+  "desc",
   0, // skip
   10 // limit - get top 10
 );
 
-items.forEach(entry => {
-  console.log(`Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`);
+items.forEach((entry) => {
+  console.log(
+    `Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`
+  );
 });
 ```
 
@@ -596,14 +599,14 @@ Get the best entry for a specific client in a leaderboard.
 
 ```typescript
 // Get current client's best entry
-const myBest = await kmClient.leaderboard.getBestEntry('all-time-high', 'desc');
+const myBest = await kmClient.leaderboard.getBestEntry("all-time-high", "desc");
 console.log(`My best: Rank ${myBest.rank}, Score ${myBest.score}`);
 
 // Get another player's best entry
 const otherBest = await kmClient.leaderboard.getBestEntry(
-  'all-time-high',
-  'desc',
-  'other-client-id'
+  "all-time-high",
+  "desc",
+  "other-client-id"
 );
 ```
 
@@ -614,15 +617,20 @@ const otherBest = await kmClient.leaderboard.getBestEntry(
 ```typescript
 // Submit a new high score
 await kmClient.leaderboard.upsertEntry(
-  'high-scores',
-  'desc',
+  "high-scores",
+  "desc",
   score,
   { playerName: player.name },
   { timestamp: Date.now() }
 );
 
 // Display top 10
-const { items } = await kmClient.leaderboard.listEntries('high-scores', 'desc', 0, 10);
+const { items } = await kmClient.leaderboard.listEntries(
+  "high-scores",
+  "desc",
+  0,
+  10
+);
 ```
 
 #### Example: Track Speed Run Times
@@ -630,15 +638,15 @@ const { items } = await kmClient.leaderboard.listEntries('high-scores', 'desc',
 ```typescript
 // Submit completion time (lower is better)
 await kmClient.leaderboard.upsertEntry(
-  'speed-run',
-  'asc',
+  "speed-run",
+  "asc",
   completionTimeInSeconds,
-  { playerName: player.name, difficulty: 'hard' },
+  { playerName: player.name, difficulty: "hard" },
   {}
 );
 
 // Get personal best
-const myBest = await kmClient.leaderboard.getBestEntry('speed-run', 'asc');
+const myBest = await kmClient.leaderboard.getBestEntry("speed-run", "asc");
 ```
 
 ### Key Points

package/dist/protocol/ws-message/index.d.ts

@@ -0,0 +1,3 @@
+export { WsMessageReader } from "./reader";
+export { WsMessageType } from "./type";
+export { WsMessageWriter } from "./writer";

package/dist/protocol/ws-message/index.js

@@ -0,0 +1,3 @@
+export { WsMessageReader } from "./reader";
+export { WsMessageType } from "./type";
+export { WsMessageWriter } from "./writer";

package/dist/protocol/ws-message/reader.d.ts

@@ -0,0 +1,11 @@
+export declare class WsMessageReader {
+    private buffer;
+    private _view;
+    private _offset;
+    constructor(buffer: ArrayBuffer);
+    readInt32(): number;
+    readUint32(): number;
+    readString(): string;
+    readUint8Array(): Uint8Array<ArrayBuffer>;
+    get end(): boolean;
+}

package/dist/protocol/ws-message/reader.js

@@ -0,0 +1,36 @@
+export class WsMessageReader {
+    buffer;
+    _view;
+    _offset = 0;
+    constructor(buffer) {
+        this.buffer = buffer;
+        this._view = new DataView(buffer);
+    }
+    readInt32() {
+        const value = this._view.getInt32(this._offset, true);
+        this._offset += 4;
+        return value;
+    }
+    readUint32() {
+        const value = this._view.getUint32(this._offset, true);
+        this._offset += 4;
+        return value;
+    }
+    readString() {
+        const length = this.readInt32();
+        let value = "";
+        for (let i = 0; i < length; i++) {
+            value += String.fromCharCode(this._view.getUint8(this._offset++));
+        }
+        return value;
+    }
+    readUint8Array() {
+        const length = this.readInt32();
+        const value = new Uint8Array(this.buffer, this._offset, length);
+        this._offset += length;
+        return value;
+    }
+    get end() {
+        return this._offset === this.buffer.byteLength;
+    }
+}

package/dist/protocol/ws-message/type.d.ts

@@ -0,0 +1,11 @@
+export declare enum WsMessageType {
+    SubscribeReq = 1,
+    SubscribeRes = 2,
+    Transaction = 3,
+    RoomUpdate = 4,
+    Error = 5,
+    Ping = 6,
+    Pong = 7,
+    UnsubscribeReq = 8,
+    UnsubscribeRes = 9
+}

package/dist/protocol/ws-message/type.js

@@ -0,0 +1,12 @@
+export var WsMessageType;
+(function (WsMessageType) {
+    WsMessageType[WsMessageType["SubscribeReq"] = 1] = "SubscribeReq";
+    WsMessageType[WsMessageType["SubscribeRes"] = 2] = "SubscribeRes";
+    WsMessageType[WsMessageType["Transaction"] = 3] = "Transaction";
+    WsMessageType[WsMessageType["RoomUpdate"] = 4] = "RoomUpdate";
+    WsMessageType[WsMessageType["Error"] = 5] = "Error";
+    WsMessageType[WsMessageType["Ping"] = 6] = "Ping";
+    WsMessageType[WsMessageType["Pong"] = 7] = "Pong";
+    WsMessageType[WsMessageType["UnsubscribeReq"] = 8] = "UnsubscribeReq";
+    WsMessageType[WsMessageType["UnsubscribeRes"] = 9] = "UnsubscribeRes";
+})(WsMessageType || (WsMessageType = {}));

package/dist/protocol/ws-message/writer.d.ts

@@ -0,0 +1,9 @@
+export declare class WsMessageWriter {
+    private _parts;
+    writeInt32(value: number): void;
+    writeUint32(value: number): void;
+    writeString(value: string): void;
+    writeChar(value: string): void;
+    writeUint8Array(value: Uint8Array): void;
+    getBuffer(): ArrayBuffer;
+}

package/dist/protocol/ws-message/writer.js

@@ -0,0 +1,45 @@
+export class WsMessageWriter {
+    _parts = [];
+    writeInt32(value) {
+        const buffer = new Uint8Array(4);
+        const view = new DataView(buffer.buffer);
+        view.setInt32(0, value, true);
+        this._parts.push(buffer);
+    }
+    writeUint32(value) {
+        const buffer = new Uint8Array(4);
+        const view = new DataView(buffer.buffer);
+        view.setUint32(0, value, true);
+        this._parts.push(buffer);
+    }
+    writeString(value) {
+        // Write length
+        this.writeInt32(value.length);
+        // Write chars
+        const buffer = new Uint8Array(value.length);
+        for (let i = 0; i < value.length; i++) {
+            buffer[i] = value.charCodeAt(i);
+        }
+        this._parts.push(buffer);
+    }
+    writeChar(value) {
+        const buffer = new Uint8Array(1);
+        buffer[0] = value.charCodeAt(0);
+        this._parts.push(buffer);
+    }
+    writeUint8Array(value) {
+        this.writeInt32(value.byteLength);
+        this._parts.push(value);
+    }
+    getBuffer() {
+        const size = this._parts.reduce((acc, part) => acc + part.byteLength, 0);
+        const buffer = new ArrayBuffer(size);
+        let offset = 0;
+        for (const part of this._parts) {
+            const view = new Uint8Array(buffer, offset);
+            view.set(part);
+            offset += part.byteLength;
+        }
+        return buffer;
+    }
+}

package/dist/services/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kokimoki-ai";
+export * from "./kokimoki-leaderboard";
+export * from "./kokimoki-storage";

package/dist/services/index.js

@@ -0,0 +1,3 @@
+export * from "./kokimoki-ai";
+export * from "./kokimoki-leaderboard";
+export * from "./kokimoki-storage";

package/dist/services/kokimoki-ai.d.ts

@@ -0,0 +1,153 @@
+import { KokimokiClient } from "../core";
+import type { Upload } from "../types";
+/**
+ * Kokimoki AI Integration Service
+ *
+ * Provides built-in AI capabilities for game applications without requiring API keys or setup.
+ * Includes text generation, structured JSON output, and image modification.
+ *
+ * **Key Features:**
+ * - Multiple AI models (GPT-4, GPT-5, Gemini variants)
+ * - Text generation with configurable creativity (temperature)
+ * - Structured JSON output for game data
+ * - AI-powered image modifications
+ * - No API keys or configuration required
+ *
+ * **Common Use Cases:**
+ * - Generate dynamic game content (quests, dialogues, stories)
+ * - Create AI opponents or NPCs with personalities
+ * - Generate quiz questions or trivia
+ * - Create game assets (character stats, item descriptions)
+ * - Transform user-uploaded images
+ * - Generate procedural content
+ *
+ * Access via `kmClient.ai`
+ *
+ * @example
+ * ```typescript
+ * // Generate story text
+ * const story = await kmClient.ai.chat({
+ *   systemPrompt: 'You are a fantasy story writer',
+ *   userPrompt: 'Write a short quest description',
+ *   temperature: 0.8
+ * });
+ *
+ * // Generate structured game data
+ * interface Enemy {
+ *   name: string;
+ *   health: number;
+ *   attack: number;
+ * }
+ * const enemy = await kmClient.ai.generateJson<Enemy>({
+ *   userPrompt: 'Create a level 5 goblin warrior'
+ * });
+ *
+ * // Transform image
+ * const modified = await kmClient.ai.modifyImage(
+ *   imageUrl,
+ *   'Make it look like pixel art'
+ * );
+ * ```
+ */
+export declare class KokimokiAiService {
+    private readonly client;
+    constructor(client: KokimokiClient);
+    /**
+     * Generate a chat response from the AI model.
+     *
+     * Sends a chat request to the AI service and returns the generated response.
+     * Supports multiple AI models including GPT and Gemini variants with configurable
+     * parameters for fine-tuning the response behavior.
+     *
+     * @param req The chat request parameters.
+     * @param req.model Optional. The AI model to use. Defaults to server-side default if not specified.
+     *                  Available models:
+     *                  - `gpt-4o`: OpenAI GPT-4 Optimized
+     *                  - `gpt-4o-mini`: Smaller, faster GPT-4 variant
+     *                  - `gpt-5`: OpenAI GPT-5 (latest)
+     *                  - `gpt-5-mini`: Smaller GPT-5 variant
+     *                  - `gpt-5-nano`: Smallest GPT-5 variant for lightweight tasks
+     *                  - `gemini-2.5-flash-lite`: Google Gemini lite variant
+     *                  - `gemini-2.5-flash`: Google Gemini fast variant
+     * @param req.systemPrompt Optional. The system message that sets the behavior and context for the AI.
+     *                         This helps define the AI's role, personality, and constraints.
+     * @param req.userPrompt The user's message or question to send to the AI.
+     * @param req.temperature Optional. Controls randomness in the response (0.0 to 1.0).
+     *                        Lower values make output more focused and deterministic,
+     *                        higher values make it more creative and varied.
+     * @param req.maxTokens Optional. The maximum number of tokens to generate in the response.
+     *                      Controls the length of the AI's output.
+     *
+     * @returns A promise that resolves to an object containing the AI-generated response.
+     * @returns {string} content The text content of the AI's response.
+     *
+     * @throws An error object if the API request fails.
+     *
+     * @example
+     * ```typescript
+     * const response = await client.ai.chat({
+     *   model: "gpt-4o",
+     *   systemPrompt: "You are a helpful coding assistant.",
+     *   userPrompt: "Explain what TypeScript is in one sentence.",
+     *   temperature: 0.7,
+     *   maxTokens: 100
+     * });
+     * console.log(response.content);
+     * ```
+     */
+    chat(req: {
+        model?: "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gemini-2.5-flash-lite" | "gemini-2.5-flash";
+        systemPrompt?: string;
+        userPrompt: string;
+        temperature?: number;
+        maxTokens?: number;
+        responseMimeType?: string;
+    }): Promise<{
+        content: string;
+    }>;
+    /**
+     * Generate structured JSON output from the AI model.
+     *
+     * Sends a chat request to the AI service with the expectation of receiving
+     * a JSON-formatted response. This is useful for scenarios where the output
+     * needs to be parsed or processed programmatically.
+     *
+     * @param req The chat request parameters.
+     * @param req.model Optional. The AI model to use. Defaults to server-side default if not specified.
+     *                  Available models:
+     *                  - `gpt-4o`: OpenAI GPT-4 Optimized
+     *                  - `gpt-4o-mini`: Smaller, faster GPT-4 variant
+     *                  - `gpt-5`: OpenAI GPT-5 (latest)
+     *                  - `gpt-5-mini`: Smaller GPT-5 variant
+     *                  - `gpt-5-nano`: Smallest GPT-5 variant for lightweight tasks
+     *                  - `gemini-2.5-flash-lite`: Google Gemini lite variant
+     *                  - `gemini-2.5-flash`: Google Gemini fast variant
+     * @param req.systemPrompt Optional. The system message that sets the behavior and context for the AI.
+     *                         This helps define the AI's role, personality, and constraints.
+     * @param req.userPrompt The user's message or question to send to the AI.
+     * @param req.temperature Optional. Controls randomness in the response (0.0 to 1.0).
+     *                        Lower values make output more focused and deterministic,
+     *                        higher values make it more creative and varied.
+     * @param req.maxTokens Optional. The maximum number of tokens to generate in the response.
+     *                      Controls the length of the AI's output.
+     *
+     * @returns A promise that resolves to the parsed JSON object generated by the AI.
+     *
+     * @throws An error object if the API request fails or if the response is not valid JSON.
+     */
+    generateJson<T extends object>(req: {
+        model?: "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gemini-2.5-flash-lite" | "gemini-2.5-flash";
+        systemPrompt?: string;
+        userPrompt: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<T>;
+    /**
+     * Modify an image using the AI service.
+     * @param baseImageUrl The URL of the base image to modify.
+     * @param prompt The modification prompt to apply to the image.
+     * @param tags Optional. Tags to associate with the image.
+     * @returns A promise that resolves to the modified image upload information.
+     */
+    modifyImage(baseImageUrl: string, prompt: string, tags?: string[]): Promise<Upload>;
+}