@kokimoki/app 2.0.0 → 2.0.1

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kokimoki-client";
+export * from "./room-subscription";
+export * from "./room-subscription-mode";

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export * from "./kokimoki-client";
+export * from "./room-subscription";
+export * from "./room-subscription-mode";

package/dist/core/kokimoki-client.d.ts

@@ -0,0 +1,361 @@
+import type TypedEmitter from "typed-emitter";
+import { KokimokiAiService, KokimokiLeaderboardService, KokimokiStorageService } from "../services";
+import { KokimokiLocalStore, KokimokiStore } from "../stores";
+import type { KokimokiClientEvents } from "../types";
+type Mutable<T> = {
+    -readonly [K in keyof T]: T[K] extends object ? Mutable<T[K]> : T[K];
+};
+type StoreValue<S> = S extends KokimokiStore<infer U> ? Mutable<U> : never;
+declare const KokimokiClient_base: {
+    new (): TypedEmitter<KokimokiClientEvents>;
+};
+/**
+ * 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 declare class KokimokiClient<ClientContextT = any> extends KokimokiClient_base {
+    readonly host: string;
+    readonly appId: string;
+    readonly code: string;
+    private _wsUrl;
+    private _apiUrl;
+    private _id?;
+    private _connectionId?;
+    private _token?;
+    private _apiHeaders?;
+    private _serverTimeOffset;
+    private _clientContext?;
+    private _ws?;
+    private _subscriptionsByName;
+    private _subscriptionsByHash;
+    private _subscribeReqPromises;
+    private _unsubscribeReqPromises;
+    private _transactionPromises;
+    private _connected;
+    private _connectPromise?;
+    private _messageId;
+    private _autoReconnect;
+    private _reconnectTimeout;
+    private _pingInterval;
+    private _clientTokenKey;
+    private _editorContext;
+    private _ai?;
+    private _storage?;
+    private _leaderboard?;
+    constructor(host: string, appId: string, code?: string);
+    get id(): string;
+    get connectionId(): string;
+    get token(): string;
+    get apiUrl(): string;
+    get apiHeaders(): Headers;
+    get clientContext(): ClientContextT & ({} | null);
+    /**
+     * Indicates whether the client is currently connected to the server.
+     */
+    get connected(): boolean;
+    get ws(): WebSocket;
+    /**
+     * Indicates whether the client is running in editor/development mode.
+     */
+    get isEditor(): boolean;
+    /**
+     * 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.
+     */
+    connect(): Promise<void>;
+    private handleInitMessage;
+    private handleBinaryMessage;
+    private handleErrorMessage;
+    private handleSubscribeResMessage;
+    private handleUnsubscribeResMessage;
+    private handleRoomUpdateMessage;
+    /**
+     * Gets the current server timestamp, accounting for client-server time offset.
+     *
+     * @returns The current server timestamp in milliseconds.
+     */
+    serverTimestamp(): number;
+    /**
+     * 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.
+     */
+    patchRoomState(room: string, update: Uint8Array): Promise<any>;
+    private sendSubscribeReq;
+    private sendUnsubscribeReq;
+    /**
+     * 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.
+     */
+    join<T extends object>(store: KokimokiStore<T>): Promise<void>;
+    /**
+     * 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.
+     */
+    leave<T extends object>(store: KokimokiStore<T>): Promise<void>;
+    /**
+     * 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();
+     * });
+     * ```
+     */
+    transact<TStores extends readonly KokimokiStore<any>[], ReturnT = void>(stores: [...TStores], handler: (proxies: {
+        [K in keyof TStores]: StoreValue<TStores[K]>;
+    }) => ReturnT | Promise<ReturnT>): Promise<ReturnT>;
+    /**
+     * Closes the client connection and cleans up resources.
+     *
+     * Disables automatic reconnection, closes the WebSocket, and clears all intervals.
+     */
+    close(): Promise<void>;
+    /**
+     * 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<T extends object>(store: KokimokiStore<T>): number;
+    /**
+     * 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<T extends object>(name: string, defaultState: T, autoJoin?: boolean): KokimokiStore<T>;
+    /**
+     * 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<T extends object>(name: string, defaultState: T): KokimokiLocalStore<T>;
+    /**
+     * 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 });
+     * ```
+     */
+    sendWebhook<T>(event: string, data: T): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Access AI capabilities including text generation, structured JSON output, and image modification.
+     */
+    get ai(): KokimokiAiService;
+    /**
+     * Access file upload and management for media files, images, and user-generated content.
+     */
+    get storage(): KokimokiStorageService;
+    /**
+     * Access player ranking and score tracking with efficient queries and pagination.
+     */
+    get leaderboard(): KokimokiLeaderboardService;
+}
+export {};