@kokimoki/app 2.1.0 → 3.0.0

package/dist/kokimoki.min.d.ts

@@ -1,4 +1,5 @@
 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';
@@ -10,6 +11,41 @@ interface Paginated<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;
@@ -107,6 +143,8 @@ declare class KokimokiAiService {
      *                        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.
@@ -194,6 +232,241 @@ declare class KokimokiAiService {
     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
  *
@@ -740,6 +1013,7 @@ declare class KokimokiClient<ClientContextT = any> extends KokimokiClient_base {
     private _clientTokenKey;
     private _editorContext;
     private _ai?;
+    private _i18n?;
     private _storage?;
     private _leaderboard?;
     constructor(host: string, appId: string, code?: string);
@@ -839,6 +1113,25 @@ declare class KokimokiClient<ClientContextT = any> extends KokimokiClient_base {
      * 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.
      *
@@ -900,6 +1193,10 @@ declare class KokimokiClient<ClientContextT = any> extends KokimokiClient_base {
      * 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.
      */
@@ -916,9 +1213,32 @@ declare enum RoomSubscriptionMode {
     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 };
-export type { KokimokiClientEvents, Paginated, Upload };
+export { KokimokiClient, KokimokiStore, getKmEnv };
+export type { AllLanguagesStatus, I18nOptions, KokimokiClientEvents, KokimokiEnv, LanguageStatus, NamespaceStatus, Paginated, RequestTranslationResult, TranslationStatus, Upload };