@kokimoki/app 3.1.3 → 3.1.5

package/dist/kokimoki.min.d.ts

@@ -1,1244 +0,0 @@
-import TypedEmitter from 'typed-emitter';
-import i18next, { i18n } from 'i18next';
-import { Snapshot } from 'valtio/vanilla';
-import * as Y from 'yjs';
-export { proxy, ref, snapshot, subscribe, useSnapshot } from 'valtio';
-export { derive, underive } from 'derive-valtio';
-export { devtools, subscribeKey, useProxy, watch } from 'valtio/utils';
-
-interface Paginated<T> {
-    items: T[];
-    total: number;
-}
-
-/**
- * Kokimoki environment configuration injected into the HTML by @kokimoki/kit.
- *
- * Parsed from `#kokimoki-env` script tag at runtime.
- * In production, placeholder values (%KM_*%) are replaced by the server.
- */
-interface KokimokiEnv {
-    /** Whether running in development mode */
-    dev: boolean;
-    /** Whether running in test/preview mode (no real deploy code) */
-    test: boolean;
-    /** WebSocket server host */
-    host: string;
-    /** Application identifier */
-    appId: string;
-    /** Base URL for routing */
-    base: string;
-    /** Base URL for static assets (CDN in production) */
-    assets: string;
-    /** Deploy code slug (production only) */
-    code?: string;
-    /** Client context JSON string - mode, player/presenter codes (production only) */
-    clientContext?: string;
-    /** App configuration JSON string (production, legacy) */
-    config?: string;
-    /** Parsed app configuration object (dev only) */
-    configObject?: unknown;
-    /** List of i18n namespace names */
-    i18nNamespaces?: string[];
-    /** List of i18n language codes */
-    i18nLanguages?: string[];
-    /** Path to i18n files (e.g., "km-i18n") */
-    i18nPath?: string;
-}
-
-type KokimokiClientEvents = {
-    connected: () => void;
-    disconnected: () => void;
-};
-
-interface Upload {
-    id: string;
-    appId: string;
-    clientId: string;
-    createdAt: Date;
-    name: string;
-    url: string;
-    size: number;
-    mimeType: string;
-    completed: boolean;
-    tags: string[];
-}
-
-/**
- * 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'
- * );
- * ```
- */
-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
-     *                  - `gemini-3-flash-preview`: Google Gemini 3 Flash preview
-     *                  - `gemini-3-pro-preview`: Google Gemini 3 Pro preview
-     * @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.
-     * @param req.imageUrls Optional. Image URLs to include with the user prompt (Gemini models only).
-     *                      Allows the AI to analyze and respond based on the provided images.
-     *
-     * @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" | "gemini-3-flash-preview" | "gemini-3-pro-preview";
-        systemPrompt?: string;
-        userPrompt: string;
-        temperature?: number;
-        maxTokens?: number;
-        responseMimeType?: string;
-        /** Image URLs to include with the user prompt (Gemini models only) */
-        imageUrls?: 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.
-     *
-     * **Important:** Your prompt must include the word "json" and should describe
-     * the expected output schema (field names, types, and structure) to ensure
-     * the AI generates properly formatted responses.
-     *
-     * @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
-     *                  - `gemini-3-flash-preview`: Google Gemini 3 Flash preview
-     *                  - `gemini-3-pro-preview`: Google Gemini 3 Pro preview
-     * @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.
-     * @param req.imageUrls Optional. Image URLs to include with the user prompt (Gemini models only).
-     *                      Allows the AI to analyze images and generate structured JSON based on them.
-     *
-     * @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" | "gemini-3-flash-preview" | "gemini-3-pro-preview";
-        systemPrompt?: string;
-        userPrompt: string;
-        temperature?: number;
-        maxTokens?: number;
-        /** Image URLs to include with the user prompt (Gemini models only) */
-        imageUrls?: string[];
-    }): 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[], model?: 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview'): Promise<Upload>;
-}
-
-/**
- * Options for creating an i18n instance.
- */
-interface I18nOptions {
-    /** Fallback language code (default: same as lng passed to init) */
-    fallbackLng?: string;
-    /** Default namespace (default: first namespace in the list) */
-    defaultNS?: string;
-    /** Array of i18next plugins to use (e.g., initReactI18next) */
-    use?: Parameters<typeof i18next.use>[0][];
-}
-/**
- * Status of a single namespace translation.
- */
-type NamespaceStatus = "available" | "processing" | "failed" | "not_available";
-/**
- * Aggregated status of a language across all namespaces.
- */
-type LanguageStatus = "available" | "processing" | "failed" | "partial";
-/**
- * Translation status for a specific language.
- */
-interface TranslationStatus {
-    /** Overall status of the language */
-    status: "available" | "processing" | "not_available";
-    /** Status per namespace */
-    namespaces: Record<string, NamespaceStatus>;
-}
-/**
- * Status of all languages that have been requested.
- */
-interface AllLanguagesStatus {
-    /** Array of language statuses */
-    languages: {
-        lng: string;
-        status: LanguageStatus;
-    }[];
-}
-/**
- * Result of requesting a translation.
- */
-interface RequestTranslationResult {
-    /** Status of the request */
-    status: "started" | "already_processing" | "already_available";
-}
-/**
- * Kokimoki i18n Service
- *
- * Provides translation loading via HTTP backend. Both development and production
- * use HTTP to load translations consistently.
- *
- * In development, translations are served by @kokimoki/kit's dev server middleware.
- * In production, translations are served from the assets CDN.
- *
- * **Key Features:**
- * - Pre-configured i18next instance creation
- * - Consistent HTTP-based loading in dev and prod
- * - URL resolution for translation namespaces
- * - AI-powered translation requests
- *
- * Access via `kmClient.i18n`
- *
- * @example
- * ```typescript
- * // Setup with React
- * import { initReactI18next } from 'react-i18next';
- *
- * export const i18n = kmClient.i18n.createI18n({
- *   use: [initReactI18next]
- * });
- *
- * // Initialize with primary language
- * await kmClient.i18n.init('en');
- *
- * // Request AI translation for another language
- * const result = await kmClient.i18n.requestTranslation('de');
- * // Then poll getTranslationStatus('de') until available
- * ```
- */
-declare class KokimokiI18nService {
-    private readonly client;
-    private initPromise;
-    private instance;
-    private options;
-    constructor(client: KokimokiClient);
-    /**
-     * Create and configure an i18next instance.
-     *
-     * This sets up the instance with plugins but does NOT initialize it.
-     * Call `init(lng)` to initialize with a specific language.
-     *
-     * @param options - Configuration options (plugins, fallback, defaultNS)
-     * @returns Configured i18next instance (not yet initialized)
-     *
-     * @example
-     * ```typescript
-     * // With React
-     * import { initReactI18next } from 'react-i18next';
-     *
-     * export const i18n = kmClient.i18n.createI18n({
-     *   use: [initReactI18next]
-     * });
-     *
-     * // Later, when you know the language:
-     * await kmClient.i18n.init('en');
-     *
-     * // Then in components:
-     * const { t } = useTranslation('game');
-     * ```
-     */
-    createI18n(options?: I18nOptions): i18n;
-    /**
-     * Initialize the i18next instance with a specific language.
-     *
-     * Must call `createI18n()` first to set up the instance.
-     *
-     * @param lng - The language code to initialize with (e.g., 'en', 'de')
-     * @returns Promise that resolves when i18n is ready
-     *
-     * @example
-     * ```typescript
-     * // Create instance first
-     * const i18n = kmClient.i18n.createI18n({ use: [initReactI18next] });
-     *
-     * // Then initialize when you know the language
-     * await kmClient.i18n.init('en');
-     * ```
-     */
-    init(lng: string): Promise<void>;
-    /**
-     * Get the URL for a translation namespace.
-     *
-     * Returns the appropriate URL based on environment:
-     * - Development: `/__kokimoki/i18n/{lng}/{ns}.json`
-     * - Production: `{assets}/km-i18n/{lng}/{ns}.json`
-     *
-     * @param lng - Language code (e.g., 'en', 'et', 'de')
-     * @param ns - Namespace (e.g., 'ui', 'game', 'setup')
-     * @returns Full URL to the translation JSON file
-     *
-     * @example
-     * ```typescript
-     * const url = kmClient.i18n.getNamespaceUrl('en', 'game');
-     * // Dev: "/__kokimoki/i18n/en/game.json"
-     * // Prod: "https://cdn.kokimoki.com/build-123/km-i18n/en/game.json"
-     * ```
-     */
-    getNamespaceUrl(lng: string, ns: string): string;
-    /**
-     * Get the list of available namespaces.
-     *
-     * @returns Array of namespace names configured in @kokimoki/kit
-     */
-    getNamespaces(): string[];
-    /**
-     * Get the list of available languages.
-     *
-     * @returns Array of language codes configured in @kokimoki/kit
-     */
-    getLanguages(): string[];
-    /**
-     * Get the status of all languages that have been requested for AI translation.
-     *
-     * Only available in production. In development, returns an empty array.
-     *
-     * @returns Promise with array of language statuses
-     *
-     * @example
-     * ```typescript
-     * const { languages } = await kmClient.i18n.getAllLanguagesStatus();
-     * // [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
-     * ```
-     */
-    getAllLanguagesStatus(): Promise<AllLanguagesStatus>;
-    /**
-     * Get the translation status for a specific language.
-     *
-     * Returns the overall status and per-namespace status for the given language.
-     * In development, returns 'available' for local languages and 'not_available' for others.
-     * In production, queries the API for the actual status.
-     *
-     * @param lng - Target language code (e.g., 'de', 'fr', 'es')
-     * @returns Promise with translation status
-     *
-     * @example
-     * ```typescript
-     * const status = await kmClient.i18n.getTranslationStatus('de');
-     * if (status.status === 'available') {
-     *   // All translations ready, can switch language
-     *   i18next.changeLanguage('de');
-     * } else if (status.status === 'processing') {
-     *   // Show loading indicator
-     * } else {
-     *   // Request translation
-     *   await kmClient.i18n.requestTranslation('de');
-     * }
-     * ```
-     */
-    getTranslationStatus(lng: string): Promise<TranslationStatus>;
-    /**
-     * Request AI translation for a target language.
-     *
-     * Triggers background AI translation jobs for all namespaces that are not yet available.
-     * Uses the build's configured primary language as the source.
-     *
-     * In development, returns 'already_available' for local languages and throws an error for others.
-     * In production, triggers the API to start translation.
-     *
-     * @param lng - Target language code (e.g., 'de', 'fr', 'es')
-     * @returns Promise with the result of the request
-     *
-     * @example
-     * ```typescript
-     * const result = await kmClient.i18n.requestTranslation('de');
-     *
-     * if (result.status === 'started') {
-     *   // Translation started, poll for status
-     *   const checkStatus = async () => {
-     *     const status = await kmClient.i18n.getTranslationStatus('de');
-     *     if (status.status === 'available') {
-     *       i18next.changeLanguage('de');
-     *     } else if (status.status === 'processing') {
-     *       setTimeout(checkStatus, 2000);
-     *     }
-     *   };
-     *   checkStatus();
-     * } else if (result.status === 'already_available') {
-     *   // Already translated, switch immediately
-     *   i18next.changeLanguage('de');
-     * }
-     * ```
-     */
-    requestTranslation(lng: string): Promise<RequestTranslationResult>;
-}
-
-/**
- * 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');
- * ```
- */
-declare class KokimokiLeaderboardService {
-    private readonly client;
-    constructor(client: KokimokiClient);
-    /**
-     * 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}`);
-     * ```
-     */
-    insertEntry<MetadataT, PrivateMetadataT>(leaderboardName: string, sortDir: "asc" | "desc", score: number, metadata: MetadataT, privateMetadata: PrivateMetadataT): Promise<{
-        rank: number;
-    }>;
-    /**
-     * 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}`);
-     * ```
-     */
-    upsertEntry<MetadataT, PrivateMetadataT>(leaderboardName: string, sortDir: "asc" | "desc", score: number, metadata: MetadataT, privateMetadata: PrivateMetadataT): Promise<{
-        rank: number;
-    }>;
-    /**
-     * 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}`);
-     * });
-     * ```
-     */
-    listEntries<MetadataT>(leaderboardName: string, sortDir: "asc" | "desc", skip?: number, limit?: number): Promise<Paginated<{
-        rank: number;
-        score: number;
-        metadata: MetadataT;
-    }>>;
-    /**
-     * 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'
-     * );
-     * ```
-     */
-    getBestEntry<MetadataT>(leaderboardName: string, sortDir: "asc" | "desc", clientId?: string): Promise<{
-        rank: number;
-        score: number;
-        metadata: MetadataT;
-    }>;
-}
-
-/**
- * Kokimoki Storage Service
- *
- * Provides file upload and management capabilities for game applications. Ideal for media files
- * (images, videos, audio) and other data not suitable for real-time stores (JSON, text files).
- *
- * **Key Features:**
- * - Upload files to cloud storage with CDN delivery
- * - Tag-based organization and filtering
- * - Query uploads by client, MIME type, or tags
- * - Pagination support for large collections
- * - Public CDN URLs for direct access
- *
- * **Common Use Cases:**
- * - Player avatars and profile images
- * - Game screenshots and replays
- * - User-generated content
- * - Asset uploads (levels, maps, custom skins)
- * - JSON configuration files
- *
- * Access via `kmClient.storage`
- *
- * @example
- * ```typescript
- * // Upload an image
- * const upload = await kmClient.storage.upload('avatar.jpg', imageBlob, ['profile']);
- *
- * // Query user's uploads
- * const myUploads = await kmClient.storage.listUploads({
- *   clientId: kmClient.id
- * });
- *
- * // Use in store
- * await kmClient.transact([store], (state) => {
- *   state.playerAvatar = upload.url;
- * });
- * ```
- */
-declare class KokimokiStorageService {
-    private readonly client;
-    constructor(client: KokimokiClient);
-    private createUpload;
-    private uploadChunks;
-    private completeUpload;
-    /**
-     * Upload a file to cloud storage.
-     *
-     * Uploads a file (Blob) to Kokimoki storage and returns an Upload object with a public CDN URL.
-     * Files are automatically chunked for efficient upload. The returned URL can be used directly
-     * in your application (e.g., in img tags or store state).
-     *
-     * @param name The filename for the upload
-     * @param blob The Blob object containing the file data
-     * @param tags Optional array of tags for organizing and filtering uploads (default: [])
-     * @returns A promise resolving to the Upload object with CDN URL and metadata
-     *
-     * @example
-     * ```typescript
-     * // Upload image with tags
-     * const upload = await kmClient.storage.upload(
-     *   'avatar.jpg',
-     *   imageBlob,
-     *   ['profile', 'avatar']
-     * );
-     *
-     * // Use the CDN URL
-     * console.log(upload.url); // https://cdn.kokimoki.com/...
-     *
-     * // Store in game state
-     * await kmClient.transact([store], (state) => {
-     *   state.players[kmClient.id].avatar = upload.url;
-     * });
-     * ```
-     */
-    upload(name: string, blob: Blob, tags?: string[]): Promise<Upload>;
-    /**
-     * Update metadata for an existing upload.
-     *
-     * Allows you to replace the tags associated with an upload. Useful for reorganizing
-     * or recategorizing uploaded files.
-     *
-     * @param id The upload ID to update
-     * @param update Object containing the new tags array
-     * @returns A promise resolving to the updated Upload object
-     *
-     * @example
-     * ```typescript
-     * // Update tags
-     * const updated = await kmClient.storage.updateUpload(upload.id, {
-     *   tags: ['archived', 'old-profile']
-     * });
-     * ```
-     */
-    updateUpload(id: string, update: {
-        tags?: string[];
-    }): Promise<Upload>;
-    /**
-     * Query uploaded files with filtering and pagination.
-     *
-     * Retrieves a list of uploads matching the specified criteria. Supports filtering by
-     * client (uploader), MIME types, and tags. Use pagination for large collections.
-     *
-     * @param filter Optional filter criteria
-     * @param filter.clientId Filter by uploader's client ID
-     * @param filter.mimeTypes Filter by MIME types (e.g., ['image/jpeg', 'image/png'])
-     * @param filter.tags Filter by tags (all specified tags must match)
-     * @param skip Number of results to skip for pagination (default: 0)
-     * @param limit Maximum number of results to return (default: 100)
-     * @returns A promise resolving to paginated Upload results with total count
-     *
-     * @example
-     * ```typescript
-     * // Get current user's images
-     * const myImages = await kmClient.storage.listUploads({
-     *   clientId: kmClient.id,
-     *   mimeTypes: ['image/jpeg', 'image/png']
-     * });
-     *
-     * // Get all profile avatars
-     * const avatars = await kmClient.storage.listUploads({
-     *   tags: ['profile', 'avatar']
-     * });
-     *
-     * // Pagination
-     * const page2 = await kmClient.storage.listUploads({}, 10, 10);
-     * ```
-     */
-    listUploads(filter?: {
-        clientId?: string;
-        mimeTypes?: string[];
-        tags?: string[];
-    }, skip?: number, limit?: number): Promise<Paginated<Upload>>;
-    /**
-     * Permanently delete an uploaded file.
-     *
-     * Removes the file from cloud storage and the CDN. The URL will no longer be accessible.
-     * This operation cannot be undone.
-     *
-     * @param id The upload ID to delete
-     * @returns A promise resolving to deletion confirmation
-     *
-     * @example
-     * ```typescript
-     * // Delete an upload
-     * const result = await kmClient.storage.deleteUpload(upload.id);
-     * console.log(`Deleted: ${result.deletedCount} file(s)`);
-     * ```
-     */
-    deleteUpload(id: string): Promise<{
-        acknowledged: boolean;
-        deletedCount: number;
-    }>;
-}
-
-declare class KokimokiStore<T extends object> {
-    readonly roomName: string;
-    readonly defaultValue: T;
-    readonly mode: RoomSubscriptionMode;
-    readonly doc: Y.Doc;
-    readonly proxy: T;
-    readonly docRoot: Y.Map<unknown>;
-    readonly connections: {
-        connectionIds: Set<string>;
-        clientIds: Set<string>;
-    };
-    private _unsubscribeConnectionsHandler;
-    constructor(roomName: string, defaultValue: T, mode?: RoomSubscriptionMode);
-    get(): Snapshot<T>;
-    subscribe(set: (value: Snapshot<T>) => void): () => void;
-    onJoin(client: KokimokiClient<any>): Promise<void>;
-    onBeforeLeave(_client: KokimokiClient): Promise<void>;
-    onLeave(_client: KokimokiClient): Promise<void>;
-}
-
-declare class KokimokiLocalStore<T extends object> extends KokimokiStore<T> {
-    private readonly localRoomName;
-    private _stateKey?;
-    private get stateKey();
-    constructor(localRoomName: string, defaultState: T);
-    getInitialUpdate(appId: string, clientId: string): {
-        roomHash: number;
-        initialUpdate: Uint8Array<ArrayBufferLike> | undefined;
-    };
-}
-
-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...');
- * });
- * ```
- */
-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 _i18n?;
-    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>;
-    /**
-     * Waits for all subscriptions to be fully joined.
-     *
-     * This is useful when you need to ensure all stores have completed their initial
-     * synchronization before proceeding (e.g., before running tests or taking snapshots).
-     *
-     * @param timeout - Maximum time to wait in milliseconds (default: 5000ms).
-     * @returns A promise that resolves when all subscriptions are joined, or when timeout is reached.
-     *
-     * @example
-     * ```ts
-     * // Wait for all stores to sync before starting game
-     * await client.waitForSubscriptions();
-     *
-     * // Wait with custom timeout
-     * await client.waitForSubscriptions(10000);
-     * ```
-     */
-    waitForSubscriptions(timeout?: number): 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 i18n URL resolution and translation loading utilities.
-     */
-    get i18n(): KokimokiI18nService;
-    /**
-     * 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;
-}
-
-declare enum RoomSubscriptionMode {
-    Read = "r",
-    Write = "w",
-    ReadWrite = "b"
-}
-
-/**
- * Parses and returns the Kokimoki environment configuration.
- *
- * The environment is injected into the HTML by @kokimoki/kit as a JSON script tag
- * with id `kokimoki-env`. In production, placeholder values are replaced by the server.
- *
- * @returns The parsed KokimokiEnv object
- * @throws Error if the kokimoki-env element is not found
- *
- * @example
- * ```typescript
- * import { getKmEnv } from '@kokimoki/app';
- *
- * const env = getKmEnv();
- * console.log(env.dev); // true in development
- * console.log(env.assets); // CDN URL in production
- *
- * // Cast i18n to your app's type if needed
- * const i18n = env.i18n as typeof i18nResources;
- * ```
- */
-declare function getKmEnv(): KokimokiEnv;
-
-declare module "valtio" {
-    function useSnapshot<T extends object>(p: T): T;
-}
-
-export { KokimokiClient, KokimokiStore, getKmEnv };
-export type { AllLanguagesStatus, I18nOptions, KokimokiClientEvents, KokimokiEnv, LanguageStatus, NamespaceStatus, Paginated, RequestTranslationResult, TranslationStatus, Upload };