@kokimoki/app 1.16.2 → 2.0.0

package/dist/kokimoki.min.js

@@ -486,7 +486,7 @@ function eventTargetAgnosticAddListener(emitter, name, listener, flags) {
 var eventsExports = events.exports;
 var EventEmitter$1 = /*@__PURE__*/getDefaultExportFromCjs(eventsExports);
 
-const KOKIMOKI_APP_VERSION = "1.16.1";
+const KOKIMOKI_APP_VERSION = "2.0.0";
 
 /**
  * Utility module to work with key-value stores.
@@ -12258,45 +12258,6 @@ class RoomSubscription {
     }
 }
 
-class KokimokiAwareness extends KokimokiStore {
-    _data;
-    _kmClients = new Set();
-    constructor(roomName, _data, mode = RoomSubscriptionMode.ReadWrite) {
-        super(`/a/${roomName}`, {}, mode);
-        this._data = _data;
-    }
-    async onJoin(client) {
-        this._kmClients.add(client);
-        await client.transact([this], ([state]) => {
-            state[client.connectionId] = {
-                clientId: client.id,
-                data: this._data,
-            };
-        });
-    }
-    async onLeave(client) {
-        this._kmClients.delete(client);
-    }
-    getClients() {
-        const clients = {};
-        const connections = this.get();
-        for (const connectionId in connections) {
-            clients[connections[connectionId].clientId] =
-                connections[connectionId].data;
-        }
-        return clients;
-    }
-    async setData(data) {
-        this._data = data;
-        const kmClients = Array.from(this._kmClients);
-        await Promise.all(kmClients.map(async (client) => {
-            await client.transact([this], ([state]) => {
-                state[client.connectionId].data = this._data;
-            });
-        }));
-    }
-}
-
 var farmhash_modern = {exports: {}};
 
 var util = {};
@@ -14863,6 +14824,528 @@ class KokimokiLocalStore extends KokimokiStore {
     }
 }
 
+/**
+ * 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'
+ * );
+ * ```
+ */
+class KokimokiAi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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);
+     * ```
+     */
+    async chat(req) {
+        const res = await fetch(`${this.client.apiUrl}/ai/chat`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify(req),
+        });
+        if (!res.ok) {
+            throw await res.json();
+        }
+        return await res.json();
+    }
+    /**
+     * 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.
+     */
+    async generateJson(req) {
+        const { content } = await this.chat({
+            ...req,
+            responseMimeType: "application/json",
+        });
+        return JSON.parse(content);
+    }
+    /**
+     * 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.
+     */
+    async modifyImage(baseImageUrl, prompt, tags = []) {
+        const res = await fetch(`${this.client.apiUrl}/ai/modify-image`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({ baseImageUrl, prompt, tags }),
+        });
+        if (!res.ok) {
+            throw await res.json();
+        }
+        return await res.json();
+    }
+}
+
+/**
+ * Kokimoki Leaderboard Service
+ *
+ * Provides efficient player ranking and score tracking with database indexes and optimized queries.
+ * Ideal for games with large numbers of players and competitive scoring.
+ *
+ * **Key Features:**
+ * - Efficient ranking with database indexes
+ * - Support for ascending (lowest-is-best) and descending (highest-is-best) sorting
+ * - Pagination for large leaderboards
+ * - Public and private metadata for entries
+ * - Insert (preserve all attempts) or upsert (keep latest only) modes
+ *
+ * **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
+ * - The leaderboard is temporary (session-based or reset frequently)
+ *
+ * Access via `kmClient.leaderboard`
+ *
+ * @example
+ * ```typescript
+ * // Submit a high score
+ * const { rank } = await kmClient.leaderboard.upsertEntry(
+ *   'high-scores',
+ *   'desc',
+ *   1500,
+ *   { playerName: 'Alice' },
+ *   {}
+ * );
+ *
+ * // Get top 10
+ * const { items } = await kmClient.leaderboard.listEntries('high-scores', 'desc', 0, 10);
+ *
+ * // Get player's best
+ * const best = await kmClient.leaderboard.getBestEntry('high-scores', 'desc');
+ * ```
+ */
+class KokimokiLeaderboard {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Add a new entry to a leaderboard.
+     *
+     * Creates a new entry each time it's called, preserving all attempts. Use this when you want
+     * to track every score submission (e.g., all game attempts).
+     *
+     * @param leaderboardName The name of the leaderboard to add the entry to
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param score The numeric score value
+     * @param metadata Public metadata visible to all players (e.g., player name, level)
+     * @param privateMetadata Private metadata only accessible via API calls (e.g., session ID)
+     * @returns A promise resolving to an object with the entry's rank
+     *
+     * @example
+     * ```typescript
+     * const { rank } = await kmClient.leaderboard.insertEntry(
+     *   'high-scores',
+     *   'desc',
+     *   1500,
+     *   { playerName: 'Alice', level: 10 },
+     *   { sessionId: 'abc123' }
+     * );
+     * console.log(`New rank: ${rank}`);
+     * ```
+     */
+    async insertEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                leaderboardName,
+                sortDir,
+                score,
+                metadata,
+                privateMetadata,
+                upsert: false,
+            }),
+        });
+        return await res.json();
+    }
+    /**
+     * Add or update the latest entry for the current client in a leaderboard.
+     *
+     * Replaces the previous entry if one exists for this client. Use this when you only want
+     * to keep the latest or best score per player (e.g., daily high score).
+     *
+     * @param leaderboardName The name of the leaderboard to upsert the entry in
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param score The numeric score value
+     * @param metadata Public metadata visible to all players (e.g., player name, completion time)
+     * @param privateMetadata Private metadata only accessible via API calls (e.g., device ID)
+     * @returns A promise resolving to an object with the entry's updated rank
+     *
+     * @example
+     * ```typescript
+     * const { rank } = await kmClient.leaderboard.upsertEntry(
+     *   'daily-scores',
+     *   'desc',
+     *   2000,
+     *   { playerName: 'Bob', completionTime: 120 },
+     *   { deviceId: 'xyz789' }
+     * );
+     * console.log(`Updated rank: ${rank}`);
+     * ```
+     */
+    async upsertEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                leaderboardName,
+                sortDir,
+                score,
+                metadata,
+                privateMetadata,
+                upsert: true,
+            }),
+        });
+        return await res.json();
+    }
+    /**
+     * List entries in a leaderboard with pagination.
+     *
+     * Retrieves a sorted list of leaderboard entries. Use skip and limit parameters for
+     * pagination (e.g., showing top 10, or implementing "load more" functionality).
+     *
+     * @param leaderboardName The name of the leaderboard to query
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param skip Number of entries to skip for pagination (default: 0)
+     * @param limit Maximum number of entries to return (default: 100)
+     * @returns A promise resolving to a paginated list of entries with rank, score, and metadata
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 scores
+     * const { items, total } = await kmClient.leaderboard.listEntries(
+     *   'weekly-scores',
+     *   'desc',
+     *   0,
+     *   10
+     * );
+     *
+     * items.forEach(entry => {
+     *   console.log(`Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`);
+     * });
+     * ```
+     */
+    async listEntries(leaderboardName, sortDir, skip = 0, limit = 100) {
+        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&skip=${skip}&limit=${limit}`, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Get the best entry for a specific client in a leaderboard.
+     *
+     * Retrieves the highest-ranked entry for a client based on the sort direction.
+     * Defaults to the current client if no clientId is provided.
+     *
+     * @param leaderboardName The name of the leaderboard to query
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param clientId The client ID to get the best entry for (optional, defaults to current client)
+     * @returns A promise resolving to the best entry with rank, score, and metadata
+     *
+     * @example
+     * ```typescript
+     * // Get current client's best entry
+     * 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'
+     * );
+     * ```
+     */
+    async getBestEntry(leaderboardName, sortDir, clientId) {
+        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries/best?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&clientId=${clientId || this.client.id}`, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+}
+
+/**
+ * Kokimoki Client - Real-time Collaborative Game Development SDK
+ *
+ * The main entry point for building multiplayer games and collaborative applications.
+ * Provides real-time state synchronization, AI integration, cloud storage, leaderboards,
+ * and more - all without complex backend setup.
+ *
+ * **Core Capabilities:**
+ * - **Real-time Stores**: Synchronized state with automatic conflict resolution (powered by Valtio + Y.js)
+ * - **Atomic Transactions**: Update multiple stores consistently with automatic batching
+ * - **AI Integration**: Built-in text generation, structured JSON output, and image modification
+ * - **Cloud Storage**: File uploads with CDN delivery and tag-based organization
+ * - **Leaderboards**: Efficient player ranking with database indexes and pagination
+ * - **Presence Tracking**: Real-time connection status for all players
+ * - **Time Sync**: Server-synchronized timestamps across all clients
+ * - **Webhooks**: Send data to external services for backend processing
+ *
+ * **Quick Start:**
+ * ```typescript
+ * import { KokimokiClient } from '@kokimoki/app';
+ *
+ * // Initialize the client
+ * const kmClient = new KokimokiClient(
+ *   'your-host.kokimoki.com',
+ *   'your-app-id',
+ *   'optional-access-code'
+ * );
+ *
+ * // Connect to the server
+ * await kmClient.connect();
+ *
+ * // Create a synchronized store
+ * interface GameState {
+ *   players: Record<string, { name: string; score: number }>;
+ *   round: number;
+ * }
+ *
+ * const gameStore = kmClient.store<GameState>('game', {
+ *   players: {},
+ *   round: 1
+ * });
+ *
+ * // Update state atomically
+ * await kmClient.transact([gameStore], ([game]) => {
+ *   game.players[kmClient.id] = { name: 'Player 1', score: 0 };
+ *   game.round = 2;
+ * });
+ *
+ * // Use in React components with Valtio
+ * import { useSnapshot } from 'valtio';
+ *
+ * function GameComponent() {
+ *   const game = useSnapshot(gameStore.proxy);
+ *   return <div>Round: {game.round}</div>;
+ * }
+ * ```
+ *
+ * **Key Features:**
+ *
+ * **1. Real-time State Management**
+ * - Create global stores shared across all players: `kmClient.store()`
+ * - Create local stores for client-side data: `kmClient.localStore()`
+ * - Automatic synchronization and conflict resolution
+ * - Use `useSnapshot()` from Valtio for reactive React components
+ *
+ * **2. Atomic Transactions**
+ * ```typescript
+ * // Update multiple stores atomically
+ * await kmClient.transact([playerStore, gameStore], ([player, game]) => {
+ *   player.score += 10;
+ *   game.lastUpdate = kmClient.serverTimestamp();
+ * });
+ * ```
+ *
+ * **3. AI Integration (No API keys required)**
+ * ```typescript
+ * // Generate text
+ * const story = await kmClient.ai.chat({
+ *   model: 'gpt-4o',
+ *   userPrompt: 'Write a quest description',
+ *   temperature: 0.8
+ * });
+ *
+ * // Generate structured data
+ * interface Quest { title: string; reward: number; }
+ * const quest = await kmClient.ai.generateJson<Quest>({
+ *   userPrompt: 'Create a level 5 quest'
+ * });
+ *
+ * // Modify images
+ * const modified = await kmClient.ai.modifyImage(url, 'Make it pixel art');
+ * ```
+ *
+ * **4. Cloud Storage**
+ * ```typescript
+ * // Upload files with tags
+ * const upload = await kmClient.storage.upload('avatar.jpg', blob, ['profile']);
+ *
+ * // Query uploads
+ * const images = await kmClient.storage.listUploads({
+ *   clientId: kmClient.id,
+ *   mimeTypes: ['image/jpeg', 'image/png']
+ * });
+ * ```
+ *
+ * **5. Leaderboards**
+ * ```typescript
+ * // Submit score (replaces previous entry)
+ * await kmClient.leaderboard.upsertEntry(
+ *   'high-scores',
+ *   'desc',
+ *   1500,
+ *   { playerName: 'Alice' },
+ *   {}
+ * );
+ *
+ * // Get top 10
+ * const top10 = await kmClient.leaderboard.listEntries('high-scores', 'desc', 0, 10);
+ * ```
+ *
+ * **6. Presence Tracking**
+ * ```typescript
+ * // Track online players
+ * const onlineClientIds = useSnapshot(gameStore.connections).clientIds;
+ * const isPlayerOnline = onlineClientIds.has(playerId);
+ * ```
+ *
+ * **Best Practices:**
+ * - Always use `kmClient.serverTimestamp()` for time-sensitive operations
+ * - Prefer Records over Arrays: `Record<string, T>` with timestamp keys
+ * - Use `kmClient.transact()` for all state updates to ensure atomicity
+ * - Tag uploads for easy filtering and organization
+ * - Use local stores for client-side settings and preferences
+ * - Leverage TypeScript generics for type-safe stores
+ *
+ * **Events:**
+ * - `connected`: Fired when client connects/reconnects to server
+ * - `disconnected`: Fired when connection is lost
+ *
+ * @template ClientContextT The type of client context data (custom user data from your backend)
+ *
+ * @example
+ * ```typescript
+ * // Listen for connection events
+ * kmClient.on('connected', () => {
+ *   console.log('Connected to Kokimoki!');
+ * });
+ *
+ * kmClient.on('disconnected', () => {
+ *   console.log('Connection lost, will auto-reconnect...');
+ * });
+ * ```
+ */
 class KokimokiClient extends EventEmitter$1 {
     host;
     appId;
@@ -14889,6 +15372,9 @@ class KokimokiClient extends EventEmitter$1 {
     _pingInterval;
     _clientTokenKey = "KM_TOKEN";
     _editorContext;
+    _ai;
+    _storage;
+    _leaderboard;
     constructor(host, appId, code = "") {
         super();
         this.host = host;
@@ -14898,6 +15384,9 @@ class KokimokiClient extends EventEmitter$1 {
         const secure = this.host.indexOf(":") === -1;
         this._wsUrl = `ws${secure ? "s" : ""}://${this.host}`;
         this._apiUrl = `http${secure ? "s" : ""}://${this.host}`;
+        // Initialize modules
+        this._ai = new KokimokiAi(this);
+        this._leaderboard = new KokimokiLeaderboard(this);
         // Set up ping interval
         const pingMsg = new WsMessageWriter();
         pingMsg.writeInt32(WsMessageType.Ping);
@@ -14958,6 +15447,9 @@ class KokimokiClient extends EventEmitter$1 {
         }
         return this._clientContext;
     }
+    /**
+     * Indicates whether the client is currently connected to the server.
+     */
     get connected() {
         return this._connected;
     }
@@ -14967,9 +15459,21 @@ class KokimokiClient extends EventEmitter$1 {
         }
         return this._ws;
     }
+    /**
+     * Indicates whether the client is running in editor/development mode.
+     */
     get isEditor() {
         return !!this._editorContext;
     }
+    /**
+     * Establishes a connection to the Kokimoki server.
+     *
+     * Handles authentication, WebSocket setup, and automatic reconnection.
+     * If already connecting, returns the existing connection promise.
+     *
+     * @returns A promise that resolves when the connection is established.
+     * @throws Error if the connection fails.
+     */
     async connect() {
         if (this._connectPromise) {
             return await this._connectPromise;
@@ -15174,10 +15678,21 @@ class KokimokiClient extends EventEmitter$1 {
             }
         }
     }
+    /**
+     * Gets the current server timestamp, accounting for client-server time offset.
+     *
+     * @returns The current server timestamp in milliseconds.
+     */
     serverTimestamp() {
         return Date.now() - this._serverTimeOffset;
     }
-    // Send Y update to room
+    /**
+     * Sends a Y.js update to a specific room.
+     *
+     * @param room - The name of the room to update.
+     * @param update - The Y.js update as a Uint8Array.
+     * @returns A promise that resolves with the server response.
+     */
     async patchRoomState(room, update) {
         const res = await fetch(`${this._apiUrl}/rooms/${room}`, {
             method: "PATCH",
@@ -15186,81 +15701,6 @@ class KokimokiClient extends EventEmitter$1 {
         });
         return await res.json();
     }
-    // Storage
-    async createUpload(name, blob, tags) {
-        const res = await fetch(`${this._apiUrl}/uploads`, {
-            method: "POST",
-            headers: this.apiHeaders,
-            body: JSON.stringify({
-                name,
-                size: blob.size,
-                mimeType: blob.type,
-                tags,
-            }),
-        });
-        return await res.json();
-    }
-    async uploadChunks(blob, chunkSize, signedUrls) {
-        return await Promise.all(signedUrls.map(async (url, index) => {
-            const start = index * chunkSize;
-            const end = Math.min(start + chunkSize, blob.size);
-            const chunk = blob.slice(start, end);
-            const res = await fetch(url, { method: "PUT", body: chunk });
-            return JSON.parse(res.headers.get("ETag") || '""');
-        }));
-    }
-    async completeUpload(id, etags) {
-        const res = await fetch(`${this._apiUrl}/uploads/${id}`, {
-            method: "PUT",
-            headers: this.apiHeaders,
-            body: JSON.stringify({ etags }),
-        });
-        return await res.json();
-    }
-    async upload(name, blob, tags = []) {
-        const { id, chunkSize, urls } = await this.createUpload(name, blob, tags);
-        const etags = await this.uploadChunks(blob, chunkSize, urls);
-        return await this.completeUpload(id, etags);
-    }
-    async updateUpload(id, update) {
-        const res = await fetch(`${this._apiUrl}/uploads/${id}`, {
-            method: "PUT",
-            headers: this.apiHeaders,
-            body: JSON.stringify(update),
-        });
-        return await res.json();
-    }
-    async listUploads(filter = {}, skip = 0, limit = 100) {
-        const url = new URL("/uploads", this._apiUrl);
-        url.searchParams.set("skip", skip.toString());
-        url.searchParams.set("limit", limit.toString());
-        if (filter.clientId) {
-            url.searchParams.set("clientId", filter.clientId);
-        }
-        if (filter.mimeTypes) {
-            url.searchParams.set("mimeTypes", filter.mimeTypes.join());
-        }
-        if (filter.tags) {
-            url.searchParams.set("tags", filter.tags.join());
-        }
-        const res = await fetch(url.href, {
-            headers: this.apiHeaders,
-        });
-        return await res.json();
-    }
-    async deleteUpload(id) {
-        const res = await fetch(`${this._apiUrl}/uploads/${id}`, {
-            method: "DELETE",
-            headers: this.apiHeaders,
-        });
-        return await res.json();
-    }
-    async exposeScriptingContext(context) {
-        // @ts-ignore
-        window.KM_SCRIPTING_CONTEXT = context;
-        // @ts-ignore
-        window.dispatchEvent(new CustomEvent("km:scriptingContextExposed"));
-    }
     async sendSubscribeReq(roomName, mode) {
         // Set up sync resolver
         const reqId = ++this._messageId;
@@ -15295,6 +15735,15 @@ class KokimokiClient extends EventEmitter$1 {
             this.ws.send(msg.getBuffer());
         });
     }
+    /**
+     * Joins a store by subscribing to its corresponding room.
+     *
+     * If already joined, this method does nothing. For local stores, initializes
+     * the store locally. For remote stores, sends a subscription request to the server.
+     *
+     * @param store - The KokimokiStore to join.
+     * @template T - The type of the store's state object.
+     */
     async join(store) {
         let subscription = this._subscriptionsByName.get(store.roomName);
         if (!subscription) {
@@ -15316,6 +15765,14 @@ class KokimokiClient extends EventEmitter$1 {
             await store.onJoin(this);
         }
     }
+    /**
+     * Leaves a store by unsubscribing from its corresponding room.
+     *
+     * Triggers the store's `onBeforeLeave` and `onLeave` lifecycle hooks.
+     *
+     * @param store - The KokimokiStore to leave.
+     * @template T - The type of the store's state object.
+     */
     async leave(store) {
         const subscription = this._subscriptionsByName.get(store.roomName);
         if (subscription) {
@@ -15328,6 +15785,27 @@ class KokimokiClient extends EventEmitter$1 {
             store.onLeave(this);
         }
     }
+    /**
+     * Executes a transaction across one or more stores.
+     *
+     * Provides proxies to the stores that track changes. All changes are batched
+     * and sent to the server atomically. The transaction ensures consistency across
+     * multiple stores.
+     *
+     * @param stores - Array of stores to include in the transaction.
+     * @param handler - Function that receives store proxies and performs modifications.
+     * @returns A promise that resolves with the return value of the handler.
+     * @template TStores - Tuple type of the stores array.
+     * @template ReturnT - The return type of the handler function.
+     *
+     * @example
+     * ```ts
+     * await client.transact([playerStore, gameStore], ([player, game]) => {
+     *   player.score += 10;
+     *   game.lastUpdate = Date.now();
+     * });
+     * ```
+     */
     async transact(stores, handler) {
         // if (!this._connected) {
         //   throw new Error("Client not connected");
@@ -15402,6 +15880,11 @@ class KokimokiClient extends EventEmitter$1 {
         }
         return returnValue;
     }
+    /**
+     * Closes the client connection and cleans up resources.
+     *
+     * Disables automatic reconnection, closes the WebSocket, and clears all intervals.
+     */
     async close() {
         this._autoReconnect = false;
         if (this._ws) {
@@ -15411,7 +15894,14 @@ class KokimokiClient extends EventEmitter$1 {
             clearInterval(this._pingInterval);
         }
     }
-    // Get room hash value for store
+    /**
+     * Gets the internal room hash identifier for a store.
+     *
+     * @param store - The store to get the room hash for.
+     * @returns The room hash as a number.
+     * @throws Error if the store hasn't been joined.
+     * @template T - The type of the store's state object.
+     */
     getRoomHash(store) {
         const subscription = this._subscriptionsByName.get(store.roomName);
         if (!subscription) {
@@ -15419,8 +15909,20 @@ class KokimokiClient extends EventEmitter$1 {
         }
         return subscription.roomHash;
     }
-    /** Initializers */
-    // store
+    /**
+     * Creates a new remote store synchronized with the server.
+     *
+     * @param name - The name of the room/store.
+     * @param defaultState - The initial state of the store.
+     * @param autoJoin - Whether to automatically join the store (default: true).
+     * @returns A new KokimokiStore instance.
+     * @template T - The type of the store's state object.
+     *
+     * @example
+     * ```ts
+     * const gameStore = client.store('game', { players: [], score: 0 });
+     * ```
+     */
     store(name, defaultState, autoJoin = true) {
         const store = new KokimokiStore(name, defaultState);
         if (autoJoin) {
@@ -15430,7 +15932,22 @@ class KokimokiClient extends EventEmitter$1 {
         }
         return store;
     }
-    // local store
+    /**
+     * Creates a new local store that persists only in the client's browser.
+     *
+     * Local stores are automatically joined and are not synchronized with the server.
+     * Data is stored locally per client and app.
+     *
+     * @param name - The name of the local store.
+     * @param defaultState - The initial state of the store.
+     * @returns A new KokimokiLocalStore instance.
+     * @template T - The type of the store's state object.
+     *
+     * @example
+     * ```ts
+     * const settingsStore = client.localStore('settings', { volume: 0.5, theme: 'dark' });
+     * ```
+     */
     localStore(name, defaultState) {
         const store = new KokimokiLocalStore(name, defaultState);
         this.join(store)
@@ -15438,122 +15955,18 @@ class KokimokiClient extends EventEmitter$1 {
             .catch(() => { });
         return store;
     }
-    // // queue
-    // queue<T extends S.Generic<unknown>>(
-    //   name: string,
-    //   schema: T,
-    //   mode: RoomSubscriptionMode,
-    //   autoJoin = true
-    // ) {
-    //   const queue = new KokimokiQueue<T>(name, schema, mode);
-    //   if (autoJoin) {
-    //     this.join(queue)
-    //       .then(() => {})
-    //       .catch(() => {});
-    //   }
-    //   return queue;
-    // }
-    // awareness
-    awareness(name, initialData, autoJoin = true) {
-        const awareness = new KokimokiAwareness(name, initialData);
-        if (autoJoin) {
-            this.join(awareness)
-                .then(() => { })
-                .catch(() => { });
-        }
-        return awareness;
-    }
-    // // req-res
-    // reqRes<Req extends S.Generic<unknown>, Res extends S.Generic<unknown>>(
-    //   serviceName: string,
-    //   reqSchema: Req,
-    //   resSchema: Res,
-    //   handleRequest: (
-    //     payload: Req["defaultValue"]
-    //   ) => Promise<Res["defaultValue"]>
-    // ) {
-    //   return new KokimokiReqRes(
-    //     this,
-    //     serviceName,
-    //     reqSchema,
-    //     resSchema,
-    //     handleRequest
-    //   );
-    // }
-    /**
-     * Add a new entry to a leaderboard
-     * @param leaderboardName
-     * @param score
-     * @param metadata
-     * @returns
-     */
-    async insertLeaderboardEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
-        const res = await fetch(`${this._apiUrl}/leaderboard-entries`, {
-            method: "POST",
-            headers: this.apiHeaders,
-            body: JSON.stringify({
-                leaderboardName,
-                sortDir,
-                score,
-                metadata,
-                privateMetadata,
-                upsert: false,
-            }),
-        });
-        return await res.json();
-    }
-    /**
-     * Add or update latest entry to a leaderboard
-     * @param leaderboardName
-     * @param score
-     * @param metadata
-     * @param privateMetadata Can only be read using the leaderboard API
-     * @returns
-     */
-    async upsertLeaderboardEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
-        const res = await fetch(`${this._apiUrl}/leaderboard-entries`, {
-            method: "POST",
-            headers: this.apiHeaders,
-            body: JSON.stringify({
-                leaderboardName,
-                sortDir,
-                score,
-                metadata,
-                privateMetadata,
-                upsert: true,
-            }),
-        });
-        return await res.json();
-    }
-    /**
-     * List entries in a leaderboard
-     * @param leaderboardName
-     * @param skip
-     * @param limit
-     * @returns
-     */
-    async listLeaderboardEntries(leaderboardName, sortDir, skip = 0, limit = 100) {
-        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
-        const res = await fetch(`${this._apiUrl}/leaderboard-entries?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&skip=${skip}&limit=${limit}`, {
-            headers: this.apiHeaders,
-        });
-        return await res.json();
-    }
     /**
-     * Get best entry in leaderboard for a client, defaults to current client
-     * @param leaderboardName
-     * @param sortDir
-     * @param clientId
-     */
-    async getBestLeaderboardEntry(leaderboardName, sortDir, clientId) {
-        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
-        const res = await fetch(`${this._apiUrl}/leaderboard-entries/best?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&clientId=${clientId || this.id}`, {
-            headers: this._apiHeaders,
-        });
-        return await res.json();
-    }
-    /**
-     * Send app data via webhook
+     * Sends app data to the server via webhook for external processing.
+     *
+     * @param event - The name of the webhook event.
+     * @param data - The data to send with the webhook.
+     * @returns A promise that resolves with the job ID.
+     * @template T - The type of the data being sent.
+     *
+     * @example
+     * ```ts
+     * await client.sendWebhook('game-ended', { winner: 'player1', score: 100 });
+     * ```
      */
     async sendWebhook(event, data) {
         const res = await fetch(`${this._apiUrl}/webhooks`, {
@@ -15564,39 +15977,33 @@ class KokimokiClient extends EventEmitter$1 {
         return await res.json();
     }
     /**
-     * Generic AI chat endpoint: send a system prompt (and optional user prompt) to get a response.
+     * Access AI capabilities including text generation, structured JSON output, and image modification.
      */
-    async chat(systemPrompt, userPrompt, temperature, maxTokens) {
-        const res = await fetch(`${this._apiUrl}/ai/chat`, {
-            method: "POST",
-            headers: this.apiHeaders,
-            body: JSON.stringify({
-                systemPrompt,
-                userPrompt,
-                temperature,
-                maxTokens,
-            }),
-        });
-        if (!res.ok) {
-            throw await res.json();
+    get ai() {
+        if (!this._ai) {
+            throw new Error("AI client not initialized");
         }
-        return await res.json();
+        return this._ai;
     }
     /**
-     * Use AI to apply prompt to an image
+     * Access file upload and management for media files, images, and user-generated content.
      */
-    async transformImage(baseImageUrl, prompt, tags = []) {
-        const res = await fetch(`${this._apiUrl}/ai/images`, {
-            method: "POST",
-            headers: this.apiHeaders,
-            body: JSON.stringify({ baseImageUrl, prompt, tags }),
-        });
-        if (!res.ok) {
-            throw await res.json();
+    get storage() {
+        if (!this._storage) {
+            throw new Error("Storage client not initialized");
         }
-        return await res.json();
+        return this._storage;
+    }
+    /**
+     * Access player ranking and score tracking with efficient queries and pagination.
+     */
+    get leaderboard() {
+        if (!this._leaderboard) {
+            throw new Error("Leaderboard client not initialized");
+        }
+        return this._leaderboard;
     }
 }
 
-export { KokimokiAwareness, KokimokiClient, KokimokiStore, RoomSubscription, RoomSubscriptionMode };
+export { KokimokiClient, KokimokiStore, RoomSubscription, RoomSubscriptionMode };
 //# sourceMappingURL=kokimoki.min.js.map