@kokimoki/app 2.0.0 → 2.0.2

package/dist/core/kokimoki-client.js

@@ -0,0 +1,819 @@
+import EventEmitter from "events";
+import * as Y from "yjs";
+import { WsMessageReader, WsMessageType, WsMessageWriter, } from "../protocol/ws-message";
+import { KokimokiAiService, KokimokiLeaderboardService, KokimokiStorageService, } from "../services";
+import { KokimokiLocalStore, KokimokiStore, KokimokiTransaction, } from "../stores";
+import { KOKIMOKI_APP_VERSION } from "../version";
+import { RoomSubscription } from "./room-subscription";
+/**
+ * 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...');
+ * });
+ * ```
+ */
+export class KokimokiClient extends EventEmitter {
+    host;
+    appId;
+    code;
+    _wsUrl;
+    _apiUrl;
+    _id;
+    _connectionId;
+    _token;
+    _apiHeaders;
+    _serverTimeOffset = 0;
+    _clientContext;
+    _ws;
+    _subscriptionsByName = new Map();
+    _subscriptionsByHash = new Map();
+    _subscribeReqPromises = new Map();
+    _unsubscribeReqPromises = new Map();
+    _transactionPromises = new Map();
+    _connected = false;
+    _connectPromise;
+    _messageId = 0;
+    _autoReconnect = true;
+    _reconnectTimeout = 0;
+    _pingInterval;
+    _clientTokenKey = "KM_TOKEN";
+    _editorContext;
+    _ai;
+    _storage;
+    _leaderboard;
+    constructor(host, appId, code = "") {
+        super();
+        this.host = host;
+        this.appId = appId;
+        this.code = code;
+        // Set up the URLs
+        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 KokimokiAiService(this);
+        this._storage = new KokimokiStorageService(this);
+        this._leaderboard = new KokimokiLeaderboardService(this);
+        // Set up ping interval
+        const pingMsg = new WsMessageWriter();
+        pingMsg.writeInt32(WsMessageType.Ping);
+        const pingBuffer = pingMsg.getBuffer();
+        this._pingInterval = setInterval(() => {
+            if (this.connected) {
+                this.ws.send(pingBuffer);
+            }
+        }, 5000);
+        // Listen for devtools messages
+        if (window.parent && window.self !== window.parent) {
+            window.addEventListener("message", (e) => {
+                console.log(`[KM TOOLS] ${e.data}`);
+                this._editorContext = e.data;
+                if (e.data === "km:clearStorage") {
+                    localStorage.removeItem(this._clientTokenKey);
+                    window.location.reload();
+                }
+                else if (e.data === "km:reload") {
+                    window.location.reload();
+                }
+            });
+        }
+    }
+    get id() {
+        if (!this._id) {
+            throw new Error("Client not connected");
+        }
+        return this._id;
+    }
+    get connectionId() {
+        if (!this._connectionId) {
+            throw new Error("Client not connected");
+        }
+        return this._connectionId;
+    }
+    get token() {
+        if (!this._token) {
+            throw new Error("Client not connected");
+        }
+        return this._token;
+    }
+    get apiUrl() {
+        if (!this._apiUrl) {
+            throw new Error("Client not connected");
+        }
+        return this._apiUrl;
+    }
+    get apiHeaders() {
+        if (!this._apiHeaders) {
+            throw new Error("Client not connected");
+        }
+        return this._apiHeaders;
+    }
+    get clientContext() {
+        if (this._clientContext === undefined) {
+            throw new Error("Client not connected");
+        }
+        return this._clientContext;
+    }
+    /**
+     * Indicates whether the client is currently connected to the server.
+     */
+    get connected() {
+        return this._connected;
+    }
+    get ws() {
+        if (!this._ws) {
+            throw new Error("Not connected");
+        }
+        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;
+        }
+        // Detect devtools
+        if (window.parent && window.self !== window.parent) {
+            await new Promise((resolve) => {
+                /* // Wait up to 500ms for parent to respond
+                const timeout = setTimeout(() => {
+                  window.removeEventListener("message", onMessage);
+                  resolve();
+                }, 500); */
+                // Listen for parent response
+                const onMessage = (e) => {
+                    // clearTimeout(timeout);
+                    window.removeEventListener("message", onMessage);
+                    if (e.data.clientKey) {
+                        this._clientTokenKey = `KM_TOKEN/${e.data.clientKey}`;
+                    }
+                    resolve();
+                };
+                window.addEventListener("message", onMessage);
+                window.parent.postMessage({ appId: this.appId }, "*");
+            });
+        }
+        // Set up the WebSocket connection
+        this._ws = new WebSocket(`${this._wsUrl}/apps/${this.appId}?clientVersion=${KOKIMOKI_APP_VERSION}`);
+        this._ws.binaryType = "arraybuffer";
+        // Close previous connection in hot-reload scenarios
+        if (window) {
+            if (!window.__KOKIMOKI_WS__) {
+                window.__KOKIMOKI_WS__ = {};
+            }
+            if (this.appId in window.__KOKIMOKI_WS__) {
+                console.log(`[Kokimoki] Closing previous connection for ${this.appId}`);
+                window.__KOKIMOKI_WS__[this.appId].close();
+            }
+            window.__KOKIMOKI_WS__[this.appId] = this;
+        }
+        // Wait for connection
+        this._connectPromise = new Promise((onInit) => {
+            // Fetch the auth token
+            const clientToken = localStorage.getItem(this._clientTokenKey);
+            // Send the app token on first connect
+            this.ws.onopen = () => {
+                this.ws.send(JSON.stringify({ type: "auth", code: this.code, token: clientToken }));
+            };
+            this.ws.onclose = () => {
+                this._connected = false;
+                this._connectPromise = undefined;
+                this._ws.onmessage = null;
+                this._ws = undefined;
+                if (window && window.__KOKIMOKI_WS__) {
+                    delete window.__KOKIMOKI_WS__[this.appId];
+                }
+                // Clean up
+                this._subscribeReqPromises.clear();
+                this._transactionPromises.clear();
+                // Attempt to reconnect
+                if (!this._autoReconnect) {
+                    return;
+                }
+                console.log(`[Kokimoki] Connection lost, attempting to reconnect in ${this._reconnectTimeout} seconds...`);
+                setTimeout(async () => await this.connect(), this._reconnectTimeout * 1000);
+                this._reconnectTimeout = Math.min(3, this._reconnectTimeout + 1);
+                // Emit disconnected event
+                this.emit("disconnected");
+            };
+            this.ws.onmessage = (e) => {
+                // console.log(`Received WS message: ${e.data}`);
+                // Handle JSON messages
+                if (typeof e.data === "string") {
+                    const message = JSON.parse(e.data);
+                    switch (message.type) {
+                        case "init":
+                            this.handleInitMessage(message);
+                            onInit();
+                            break;
+                    }
+                    return;
+                }
+                // Handle binary messages
+                this.handleBinaryMessage(e.data);
+            };
+        });
+        await this._connectPromise;
+        this._connected = true;
+        // Connection established
+        console.log(`[Kokimoki] Client id: ${this.id}`);
+        console.log(`[Kokimoki] Client context:`, this.clientContext);
+        // Restore subscriptions if reconnected
+        const roomNames = Array.from(this._subscriptionsByName.keys()).map((name) => `"${name}"`);
+        if (roomNames.length) {
+            console.log(`[Kokimoki] Restoring subscriptions: ${roomNames}`);
+        }
+        for (const subscription of this._subscriptionsByName.values()) {
+            try {
+                await this.join(subscription.store);
+            }
+            catch (err) {
+                console.error(`[Kokimoki] Failed to restore subscription for "${subscription.roomName}":`, err);
+            }
+        }
+        // Emit connected event
+        this._reconnectTimeout = 0;
+        this.emit("connected");
+    }
+    handleInitMessage(message) {
+        localStorage.setItem(this._clientTokenKey, message.clientToken);
+        this._id = message.clientId;
+        this._connectionId = message.id;
+        this._token = message.appToken;
+        this._clientContext = message.clientContext;
+        // Set up the auth headers
+        this._apiHeaders = new Headers({
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        });
+    }
+    handleBinaryMessage(data) {
+        const reader = new WsMessageReader(data);
+        const type = reader.readInt32();
+        switch (type) {
+            case WsMessageType.SubscribeRes:
+                this.handleSubscribeResMessage(reader);
+                break;
+            case WsMessageType.UnsubscribeRes:
+                this.handleUnsubscribeResMessage(reader);
+                break;
+            case WsMessageType.RoomUpdate:
+                this.handleRoomUpdateMessage(reader);
+                break;
+            case WsMessageType.Error:
+                this.handleErrorMessage(reader);
+                break;
+            case WsMessageType.Pong: {
+                const s = reader.readInt32();
+                const ms = reader.readInt32();
+                this._serverTimeOffset = Date.now() - s * 1000 - ms;
+                break;
+            }
+        }
+    }
+    handleErrorMessage(msg) {
+        const reqId = msg.readInt32();
+        const error = msg.readString();
+        const subscribeReqPromise = this._subscribeReqPromises.get(reqId);
+        const transactionPromise = this._transactionPromises.get(reqId);
+        if (subscribeReqPromise) {
+            this._subscribeReqPromises.delete(reqId);
+            subscribeReqPromise.reject(error);
+        }
+        else if (transactionPromise) {
+            this._transactionPromises.delete(reqId);
+            transactionPromise.reject(error);
+        }
+        else {
+            console.warn(`Received error for unknown request ${reqId}: ${error}`);
+        }
+    }
+    handleSubscribeResMessage(msg) {
+        const reqId = msg.readInt32();
+        const roomHash = msg.readUint32();
+        const promise = this._subscribeReqPromises.get(reqId);
+        if (promise) {
+            this._subscribeReqPromises.delete(reqId);
+            // In Write mode, no initial state is sent
+            if (!msg.end) {
+                promise.resolve(roomHash, msg.readUint8Array());
+            }
+            else {
+                promise.resolve(roomHash);
+            }
+        }
+    }
+    handleUnsubscribeResMessage(msg) {
+        const reqId = msg.readInt32();
+        const promise = this._unsubscribeReqPromises.get(reqId);
+        if (promise) {
+            this._unsubscribeReqPromises.delete(reqId);
+            promise.resolve();
+        }
+    }
+    handleRoomUpdateMessage(msg) {
+        const appliedId = msg.readInt32();
+        const roomHash = msg.readUint32();
+        // Apply update if not in Write mode
+        if (!msg.end) {
+            const subscription = this._subscriptionsByHash.get(roomHash);
+            if (subscription) {
+                Y.applyUpdate(subscription.store.doc, msg.readUint8Array(), this);
+            }
+            else {
+                console.warn(`Received update for unknown room ${roomHash}`);
+            }
+        }
+        // Check transaction resolves
+        for (const [transactionId, { resolve },] of this._transactionPromises.entries()) {
+            if (appliedId >= transactionId) {
+                this._transactionPromises.delete(transactionId);
+                resolve();
+            }
+        }
+    }
+    /**
+     * Gets the current server timestamp, accounting for client-server time offset.
+     *
+     * @returns The current server timestamp in milliseconds.
+     */
+    serverTimestamp() {
+        return Date.now() - this._serverTimeOffset;
+    }
+    /**
+     * 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",
+            headers: this.apiHeaders,
+            body: update,
+        });
+        return await res.json();
+    }
+    async sendSubscribeReq(roomName, mode) {
+        // Set up sync resolver
+        const reqId = ++this._messageId;
+        return await new Promise((resolve, reject) => {
+            this._subscribeReqPromises.set(reqId, {
+                resolve: (roomHash, initialUpdate) => {
+                    resolve({ roomHash, initialUpdate });
+                },
+                reject,
+            });
+            // Send subscription request
+            const msg = new WsMessageWriter();
+            msg.writeInt32(WsMessageType.SubscribeReq);
+            msg.writeInt32(reqId);
+            msg.writeString(roomName);
+            msg.writeChar(mode);
+            this.ws.send(msg.getBuffer());
+        });
+    }
+    async sendUnsubscribeReq(roomHash) {
+        const reqId = ++this._messageId;
+        return await new Promise((resolve, reject) => {
+            this._unsubscribeReqPromises.set(reqId, {
+                resolve,
+                reject,
+            });
+            // Send unsubscribe request
+            const msg = new WsMessageWriter();
+            msg.writeInt32(WsMessageType.UnsubscribeReq);
+            msg.writeInt32(reqId);
+            msg.writeUint32(roomHash);
+            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) {
+            subscription = new RoomSubscription(this, store);
+            this._subscriptionsByName.set(store.roomName, subscription);
+        }
+        // Send subscription request if connected to server
+        if (!subscription.joined) {
+            let res;
+            if (store instanceof KokimokiLocalStore) {
+                res = store.getInitialUpdate(this.appId, this.id);
+            }
+            else {
+                res = await this.sendSubscribeReq(store.roomName, store.mode);
+            }
+            this._subscriptionsByHash.set(res.roomHash, subscription);
+            await subscription.applyInitialResponse(res.roomHash, res.initialUpdate);
+            // Trigger onJoin event
+            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) {
+            await store.onBeforeLeave(this);
+            await this.sendUnsubscribeReq(subscription.roomHash);
+            this._subscriptionsByName.delete(store.roomName);
+            this._subscriptionsByHash.delete(subscription.roomHash);
+            subscription.close();
+            // Trigger onLeave event
+            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");
+        // }
+        const transaction = new KokimokiTransaction(stores);
+        // @ts-ignore
+        const returnValue = await handler(transaction.getProxies());
+        const { updates, consumedMessages } = await transaction.getUpdates();
+        if (!updates.length) {
+            return returnValue;
+        }
+        // Construct buffers
+        const remoteUpdateWriter = new WsMessageWriter();
+        const localUpdateWriter = new WsMessageWriter();
+        // Write message type
+        remoteUpdateWriter.writeInt32(WsMessageType.Transaction);
+        // Update and write transaction ID
+        const transactionId = ++this._messageId;
+        remoteUpdateWriter.writeInt32(transactionId);
+        localUpdateWriter.writeInt32(transactionId);
+        // Write room hashes where messages were consumed (remote only)
+        remoteUpdateWriter.writeInt32(consumedMessages.size);
+        for (const roomName of consumedMessages) {
+            const subscription = this._subscriptionsByName.get(roomName);
+            if (!subscription) {
+                throw new Error(`Cannot consume message in "${roomName}" because it hasn't been joined`);
+            }
+            remoteUpdateWriter.writeUint32(subscription.roomHash);
+        }
+        // Write updates
+        let localUpdates = 0, remoteUpdates = 0;
+        for (const { roomName, update } of updates) {
+            const subscription = this._subscriptionsByName.get(roomName);
+            if (!subscription) {
+                throw new Error(`Cannot send update to "${roomName}" because it hasn't been joined`);
+            }
+            if (subscription.store instanceof KokimokiLocalStore) {
+                localUpdates++;
+                localUpdateWriter.writeUint32(subscription.roomHash);
+                localUpdateWriter.writeUint8Array(update);
+            }
+            else {
+                remoteUpdates++;
+                remoteUpdateWriter.writeUint32(subscription.roomHash);
+                remoteUpdateWriter.writeUint8Array(update);
+            }
+        }
+        // Wait for server to apply transaction
+        if (remoteUpdates) {
+            const remoteBuffer = remoteUpdateWriter.getBuffer();
+            await new Promise((resolve, reject) => {
+                this._transactionPromises.set(transactionId, { resolve, reject });
+                // Send update to server
+                try {
+                    this.ws.send(remoteBuffer);
+                }
+                catch (e) {
+                    // Not connected
+                    console.log("Failed to send update to server:", e);
+                    // Delete transaction promise
+                    this._transactionPromises.delete(transactionId);
+                    // TODO: merge updates or something
+                    reject(e);
+                }
+            });
+        }
+        // Apply local updates
+        if (localUpdates) {
+            const localBuffer = localUpdateWriter.getBuffer();
+            const reader = new WsMessageReader(localBuffer);
+            this.handleRoomUpdateMessage(reader);
+        }
+        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) {
+            this._ws.close();
+        }
+        if (this._pingInterval) {
+            clearInterval(this._pingInterval);
+        }
+    }
+    /**
+     * 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) {
+            throw new Error(`Store "${store.roomName}" not joined`);
+        }
+        return subscription.roomHash;
+    }
+    /**
+     * 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) {
+            this.join(store)
+                .then(() => { })
+                .catch(() => { });
+        }
+        return 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)
+            .then(() => { })
+            .catch(() => { });
+        return store;
+    }
+    /**
+     * 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`, {
+            method: "POST",
+            headers: this.apiHeaders,
+            body: JSON.stringify({ event, data }),
+        });
+        return await res.json();
+    }
+    /**
+     * Access AI capabilities including text generation, structured JSON output, and image modification.
+     */
+    get ai() {
+        if (!this._ai) {
+            throw new Error("AI client not initialized");
+        }
+        return this._ai;
+    }
+    /**
+     * Access file upload and management for media files, images, and user-generated content.
+     */
+    get storage() {
+        if (!this._storage) {
+            throw new Error("Storage client not initialized");
+        }
+        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;
+    }
+}