@kokimoki/app 2.1.0 → 3.0.0

package/dist/services/kokimoki-ai.js

@@ -1,15 +1,18 @@
+import { z } from "zod/v4";
 /**
  * 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.
+ * All generation methods are async job-based - they submit a job and return immediately with a jobId.
+ * Use the corresponding poll method to wait for the result.
  *
  * **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
+ * - Structured JSON output with Zod schema validation
+ * - AI-powered image generation and modification
+ * - Job-based async processing with polling support
+ * - Resumable after page reload (persist jobId)
  *
  * **Common Use Cases:**
  * - Generate dynamic game content (quests, dialogues, stories)
@@ -23,28 +26,24 @@
  *
  * @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
+ * const enemySchema = z.object({
+ *   name: z.string(),
+ *   health: z.number(),
+ *   attack: z.number()
  * });
  *
- * // 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'
+ * // Submit job
+ * const { jobId } = await kmClient.ai.generateJson({
+ *   schema: enemySchema,
+ *   prompt: 'Create a level 5 goblin warrior'
  * });
  *
- * // Transform image
- * const modified = await kmClient.ai.modifyImage(
- *   imageUrl,
- *   'Make it look like pixel art'
- * );
+ * // Save jobId to store for persistence across reloads
+ * await saveJobId(jobId);
+ *
+ * // Poll for result (can resume after reload)
+ * const enemy = await kmClient.ai.pollJson(jobId, { schema: enemySchema });
  * ```
  */
 export class KokimokiAiService {
@@ -52,56 +51,37 @@ export class KokimokiAiService {
     constructor(client) {
         this.client = client;
     }
+    // ============================================================
+    // Job Submission Methods
+    // ============================================================
     /**
-     * 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.
-     *
-     * @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.
+     * Generate text content from the AI model.
+     *
+     * Submits a text generation job and returns immediately with a jobId.
+     * Use `pollText()` to wait for the result.
+     *
+     * @param req The generation request parameters.
+     * @returns A promise that resolves to an object containing the jobId.
      *
      * @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
+     * const { jobId } = await kmClient.ai.generateText({
+     *   systemPrompt: 'You are a fantasy story writer',
+     *   prompt: 'Write a short quest description',
+     *   temperature: 0.8
      * });
-     * console.log(response.content);
+     *
+     * const text = await kmClient.ai.pollText(jobId);
      * ```
      */
-    async chat(req) {
-        const res = await fetch(`${this.client.apiUrl}/ai/chat`, {
+    async generateText(req) {
+        const res = await fetch(`${this.client.apiUrl}/ai/jobs`, {
             method: "POST",
             headers: this.client.apiHeaders,
-            body: JSON.stringify(req),
+            body: JSON.stringify({
+                type: "text",
+                ...req,
+            }),
         });
         if (!res.ok) {
             throw await res.json();
@@ -111,64 +91,176 @@ export class KokimokiAiService {
     /**
      * 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.
+     * Submits a JSON generation job and returns immediately with a jobId.
+     * The Zod schema is converted to JSON Schema and sent to the AI.
+     * Use `pollJson()` to wait for the result with type inference.
+     *
+     * @param req The generation request parameters including Zod schema.
+     * @returns A promise that resolves to an object containing the jobId.
+     *
+     * @example
+     * ```typescript
+     * const enemySchema = z.object({
+     *   name: z.string(),
+     *   health: z.number(),
+     *   attack: z.number()
+     * });
+     *
+     * const { jobId } = await kmClient.ai.generateJson({
+     *   schema: enemySchema,
+     *   prompt: 'Create a level 5 goblin warrior'
+     * });
+     *
+     * // Poll with schema for type inference and validation
+     * const enemy = await kmClient.ai.pollJson(jobId, { schema: enemySchema });
+     * ```
      */
     async generateJson(req) {
-        const { content } = await this.chat({
-            ...req,
-            responseMimeType: "application/json",
+        const { schema, ...rest } = req;
+        const jsonSchema = z.toJSONSchema(schema);
+        const res = await fetch(`${this.client.apiUrl}/ai/jobs`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                type: "json",
+                jsonSchema,
+                ...rest,
+            }),
         });
-        return JSON.parse(content);
+        if (!res.ok) {
+            throw await res.json();
+        }
+        return await res.json();
     }
     /**
-     * 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.
+     * Generate or modify an image using the AI model.
+     *
+     * Submits an image generation job and returns immediately with a jobId.
+     * Use `pollImage()` to wait for the result.
+     *
+     * @param req The generation request parameters.
+     * @returns A promise that resolves to an object containing the jobId.
+     *
+     * @example
+     * ```typescript
+     * // Modify existing image
+     * const { jobId } = await kmClient.ai.generateImage({
+     *   imageUrls: [imageUrl],
+     *   prompt: 'Make it look like pixel art'
+     * });
+     *
+     * const image = await kmClient.ai.pollImage(jobId);
+     * ```
      */
-    async modifyImage(baseImageUrl, prompt, tags = [], model = 'gemini-2.5-flash-image') {
-        const res = await fetch(`${this.client.apiUrl}/ai/modify-image`, {
+    async generateImage(req) {
+        const res = await fetch(`${this.client.apiUrl}/ai/jobs`, {
             method: "POST",
             headers: this.client.apiHeaders,
-            body: JSON.stringify({ baseImageUrl, prompt, tags, model }),
+            body: JSON.stringify({
+                type: "image",
+                model: req.model ?? "gemini-2.5-flash-image",
+                prompt: req.prompt,
+                imageUrls: req.imageUrls,
+                tags: req.tags ?? [],
+            }),
         });
         if (!res.ok) {
             throw await res.json();
         }
         return await res.json();
     }
+    // ============================================================
+    // Job Status & Polling Methods
+    // ============================================================
+    /**
+     * Get the current status of an AI job.
+     *
+     * One-shot status check without polling.
+     *
+     * @param jobId The job ID to check.
+     * @returns A promise that resolves to the job information.
+     */
+    async getJob(jobId) {
+        const res = await fetch(`${this.client.apiUrl}/ai/jobs/${jobId}`, {
+            method: "GET",
+            headers: this.client.apiHeaders,
+        });
+        if (!res.ok) {
+            throw await res.json();
+        }
+        return await res.json();
+    }
+    /**
+     * Poll a text generation job until completion.
+     *
+     * @param jobId The job ID to poll.
+     * @param options Polling options (interval, timeout, progress callback).
+     * @returns A promise that resolves to the generated text.
+     * @throws If the job fails or times out.
+     */
+    async pollText(jobId, options) {
+        const result = await this.pollJob(jobId, options);
+        return result;
+    }
+    /**
+     * Poll a JSON generation job until completion.
+     *
+     * @param jobId The job ID to poll.
+     * @param options Polling options including the Zod schema for validation.
+     * @returns A promise that resolves to the parsed and validated JSON.
+     * @throws If the job fails, times out, or validation fails.
+     *
+     * @example
+     * ```typescript
+     * const enemy = await kmClient.ai.pollJson(savedJobId, {
+     *   schema: enemySchema,
+     *   timeout: 60000,
+     *   onProgress: (status) => console.log('Status:', status)
+     * });
+     * ```
+     */
+    async pollJson(jobId, options) {
+        const { schema, ...pollOptions } = options;
+        const result = await this.pollJob(jobId, pollOptions);
+        return schema.parse(result);
+    }
+    /**
+     * Poll an image generation job until completion.
+     *
+     * @param jobId The job ID to poll.
+     * @param options Polling options (interval, timeout, progress callback).
+     * @returns A promise that resolves to the upload information.
+     * @throws If the job fails or times out.
+     */
+    async pollImage(jobId, options) {
+        const result = await this.pollJob(jobId, options);
+        return result;
+    }
+    /**
+     * Internal polling implementation.
+     */
+    async pollJob(jobId, options) {
+        const pollInterval = Math.max(1000, options?.pollInterval ?? 2000);
+        const timeout = options?.timeout ?? 120000;
+        const startTime = Date.now();
+        while (true) {
+            const job = await this.getJob(jobId);
+            // Call progress callback
+            options?.onProgress?.(job.status);
+            if (job.status === "completed") {
+                return job.result;
+            }
+            if (job.status === "failed") {
+                throw new Error(job.error?.message ?? "AI job failed");
+            }
+            // processing and queued both continue polling
+            // queued jobs will be promoted when slots become available
+            // Check timeout
+            if (Date.now() - startTime > timeout) {
+                throw new Error(`AI job timed out after ${timeout}ms`);
+            }
+            // Wait before next poll
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+    }
 }

package/dist/services/kokimoki-i18n.d.ts

@@ -0,0 +1,259 @@
+import i18next, { type i18n } from "i18next";
+import type { KokimokiClient } from "../core";
+import type { PollOptions } from "../types";
+/**
+ * Options for creating an i18n instance.
+ */
+export 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.
+ */
+export type NamespaceStatus = "available" | "processing" | "failed" | "not_available";
+/**
+ * Aggregated status of a language across all namespaces.
+ */
+export type LanguageStatus = "available" | "processing" | "failed" | "partial";
+/**
+ * Translation status for a specific language.
+ */
+export 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.
+ */
+export interface AllLanguagesStatus {
+    /** Array of language statuses */
+    languages: {
+        lng: string;
+        status: LanguageStatus;
+    }[];
+}
+/**
+ * Result of requesting a translation.
+ */
+export interface RequestTranslationResult {
+    /** Language code that was requested */
+    lng: string;
+    /** 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 with polling support
+ *
+ * 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 and wait for it
+ * await kmClient.i18n.requestTranslation('de');
+ * await kmClient.i18n.pollTranslation('de', {
+ *   onProgress: (status) => console.log('Translation status:', status.status)
+ * });
+ *
+ * // Now safe to switch language
+ * i18next.changeLanguage('de');
+ * ```
+ */
+export 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 and language source:
+     * - Development (local language): `/__kokimoki/i18n/{lng}/{ns}.json`
+     * - Development (AI-translated): `{buildUrl}km-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 (local): "/__kokimoki/i18n/en/game.json"
+     * // Dev (AI): "https://builds.kokimoki.com/build-123/km-i18n/de/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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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 === 'already_available') {
+     *   // Already translated, switch immediately
+     *   i18next.changeLanguage('de');
+     * } else {
+     *   // Poll until ready
+     *   await kmClient.i18n.pollTranslation('de', {
+     *     onProgress: (status) => console.log('Status:', status.status)
+     *   });
+     *   i18next.changeLanguage('de');
+     * }
+     * ```
+     */
+    requestTranslation(lng: string): Promise<RequestTranslationResult>;
+    /**
+     * Poll a translation request until all namespaces are available.
+     *
+     * @param lng - The language code to poll for.
+     * @param options - Polling options (interval, timeout, progress callback).
+     * @returns Promise that resolves when all namespaces are available.
+     * @throws If the translation fails or times out.
+     *
+     * @example
+     * ```typescript
+     * // Request and poll with progress
+     * await kmClient.i18n.requestTranslation('de');
+     * await kmClient.i18n.pollTranslation('de', {
+     *   timeout: 60000,
+     *   onProgress: (status) => {
+     *     console.log('Overall:', status.status);
+     *     console.log('Namespaces:', status.namespaces);
+     *   }
+     * });
+     *
+     * // Now safe to switch
+     * i18next.changeLanguage('de');
+     * ```
+     */
+    pollTranslation(lng: string, options?: PollOptions<TranslationStatus>): Promise<void>;
+}