@kokimoki/app 3.1.1 → 3.1.3

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { APP_META_STORE_NAME } from "./core/kokimoki-client";
 export type { AppMetaState } from "./core/kokimoki-client";
 export { KokimokiStore } from "./stores";
 export type { KokimokiClientEvents, KokimokiEnv, Paginated, PollOptions, Upload, } from "./types";
-export type { AllLanguagesStatus, I18nOptions, LanguageStatus, NamespaceStatus, RequestTranslationResult, TranslationStatus, } from "./services/kokimoki-i18n";
+export type { I18nOptions, TranslationStatus as LanguageStatus, TranslationStatus as NamespaceStatus, TranslationStatus, } from "./services/kokimoki-i18n";
 export type { AiJob, AiJobStatus, AiJobType } from "./services/kokimoki-ai";
 export { getKmClient } from "./utils/kokimoki-client";
 export { getKmEnv } from "./utils/kokimoki-env";

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

@@ -1,16 +1,15 @@
-import { z, ZodType } from "zod/v4";
+import { ZodType } from "zod/v4";
 import { KokimokiClient } from "../core";
-import type { PollOptions, Upload } from "../types";
 /** AI job status */
 export type AiJobStatus = "processing" | "queued" | "completed" | "failed";
 /** AI job type */
 export type AiJobType = "text" | "json" | "image";
 /** AI job information */
-export interface AiJob {
+export interface AiJob<T = unknown> {
     jobId: string;
     type: AiJobType;
     status: AiJobStatus;
-    result?: unknown;
+    result?: T;
     error?: {
         message: string;
         code?: string;
@@ -109,7 +108,7 @@ export declare class KokimokiAiService {
      * 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.
+     * Use `getJob()` to poll for the result.
      *
      * @param req The generation request parameters.
      * @returns A promise that resolves to an object containing the jobId.
@@ -122,7 +121,8 @@ export declare class KokimokiAiService {
      *   temperature: 0.8
      * });
      *
-     * const text = await kmClient.ai.pollText(jobId);
+     * const job = await kmClient.ai.getJob<string>(jobId);
+     * console.log('Generated quest:', job.result);
      * ```
      */
     generateText(req: TextGenerateRequest): Promise<JobSubmitResponse>;
@@ -131,7 +131,7 @@ export declare class KokimokiAiService {
      *
      * 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.
+     * Use `getJob()` to poll 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.
@@ -144,13 +144,16 @@ export declare class KokimokiAiService {
      *   attack: z.number()
      * });
      *
+     * type Enemy = z.infer<typeof enemySchema>;
+     *
      * 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 });
+     * const job = await kmClient.ai.getJob<Enemy>(jobId);
+     * console.log('Generated enemy:', job.result);
      * ```
      */
     generateJson<T extends ZodType>(req: JsonGenerateRequest<T>): Promise<JobSubmitResponse>;
@@ -158,7 +161,7 @@ export declare class KokimokiAiService {
      * 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.
+     * Use `getJob()` to poll for the result.
      *
      * @param req The generation request parameters.
      * @returns A promise that resolves to an object containing the jobId.
@@ -171,7 +174,8 @@ export declare class KokimokiAiService {
      *   prompt: 'Make it look like pixel art'
      * });
      *
-     * const image = await kmClient.ai.pollImage(jobId);
+     * const job = await kmClient.ai.getJob<string>(jobId);
+     * console.log('Generated image:', job.result);
      * ```
      */
     generateImage(req: ImageGenerateRequest): Promise<JobSubmitResponse>;
@@ -183,48 +187,6 @@ export declare class KokimokiAiService {
      * @param jobId The job ID to check.
      * @returns A promise that resolves to the job information.
      */
-    getJob(jobId: string): Promise<AiJob>;
-    /**
-     * 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.
-     */
-    pollText(jobId: string, options?: PollOptions<AiJobStatus>): Promise<string>;
-    /**
-     * 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)
-     * });
-     * ```
-     */
-    pollJson<T extends ZodType>(jobId: string, options: PollOptions<AiJobStatus> & {
-        schema: T;
-    }): Promise<z.infer<T>>;
-    /**
-     * 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.
-     */
-    pollImage(jobId: string, options?: PollOptions<AiJobStatus>): Promise<Upload>;
-    /**
-     * Internal polling implementation.
-     */
-    private pollJob;
+    getJob<T = unknown>(jobId: string): Promise<AiJob<T>>;
 }
 export {};

package/dist/services/kokimoki-ai.js

@@ -58,7 +58,7 @@ export class KokimokiAiService {
      * 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.
+     * Use `getJob()` to poll for the result.
      *
      * @param req The generation request parameters.
      * @returns A promise that resolves to an object containing the jobId.
@@ -71,7 +71,8 @@ export class KokimokiAiService {
      *   temperature: 0.8
      * });
      *
-     * const text = await kmClient.ai.pollText(jobId);
+     * const job = await kmClient.ai.getJob<string>(jobId);
+     * console.log('Generated quest:', job.result);
      * ```
      */
     async generateText(req) {
@@ -93,7 +94,7 @@ export class KokimokiAiService {
      *
      * 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.
+     * Use `getJob()` to poll 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.
@@ -106,13 +107,16 @@ export class KokimokiAiService {
      *   attack: z.number()
      * });
      *
+     * type Enemy = z.infer<typeof enemySchema>;
+     *
      * 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 });
+     * const job = await kmClient.ai.getJob<Enemy>(jobId);
+     * console.log('Generated enemy:', job.result);
      * ```
      */
     async generateJson(req) {
@@ -136,7 +140,7 @@ export class KokimokiAiService {
      * 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.
+     * Use `getJob()` to poll for the result.
      *
      * @param req The generation request parameters.
      * @returns A promise that resolves to an object containing the jobId.
@@ -149,7 +153,8 @@ export class KokimokiAiService {
      *   prompt: 'Make it look like pixel art'
      * });
      *
-     * const image = await kmClient.ai.pollImage(jobId);
+     * const job = await kmClient.ai.getJob<string>(jobId);
+     * console.log('Generated image:', job.result);
      * ```
      */
     async generateImage(req) {
@@ -169,9 +174,6 @@ export class KokimokiAiService {
         }
         return await res.json();
     }
-    // ============================================================
-    // Job Status & Polling Methods
-    // ============================================================
     /**
      * Get the current status of an AI job.
      *
@@ -190,77 +192,4 @@ export class KokimokiAiService {
         }
         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

@@ -1,6 +1,5 @@
 import i18next, { type i18n } from "i18next";
 import type { KokimokiClient } from "../core";
-import type { PollOptions } from "../types";
 /**
  * Options for creating an i18n instance.
  */
@@ -15,39 +14,7 @@ export interface I18nOptions {
 /**
  * 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";
-}
+export type TranslationStatus = "available" | "processing" | "failed";
 /**
  * Kokimoki i18n Service
  *
@@ -61,7 +28,7 @@ export interface RequestTranslationResult {
  * - 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
+ * - AI-powered translation requests and status polling
  *
  * Access via `kmClient.i18n`
  *
@@ -75,16 +42,20 @@ export interface RequestTranslationResult {
  * });
  *
  * // Initialize with primary language
- * await kmClient.i18n.init('en');
+ * await kmClient.i18n.init();
  *
  * // 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');
+ * // Poll until ready
+ * const checkInterval = setInterval(async () => {
+ *  const status = await kmClient.i18n.getTranslationStatus('de');
+ *  if (status.status === 'available') {
+ *    clearInterval(checkInterval);
+ *    // Now safe to switch language
+ *    i18next.changeLanguage('de');
+ *  }
+ * }, 2000);
  * ```
  */
 export declare class KokimokiI18nService {
@@ -174,17 +145,25 @@ export declare class KokimokiI18nService {
      */
     getLanguages(): string[];
     /**
-     * Get the status of all languages that have been requested for AI translation.
+     * 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.
      *
-     * @returns Promise with array of language statuses
+     * @param lng - Target language code (e.g., 'de', 'fr', 'es')
+     * @returns Promise with the translation status
      *
      * @example
      * ```typescript
-     * const { languages } = await kmClient.i18n.getAllLanguagesStatus();
-     * // [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
+     * const status = await kmClient.i18n.requestTranslation('de');
+     *
+     * if (status === 'available') {
+     *   // Already translated, switch immediately
+     *   i18next.changeLanguage('de');
+     * }
      * ```
      */
-    getAllLanguagesStatus(): Promise<AllLanguagesStatus>;
+    requestTranslation(lng: string): Promise<TranslationStatus>;
     /**
      * Get the translation status for a specific language.
      *
@@ -208,55 +187,4 @@ export declare class KokimokiI18nService {
      * ```
      */
     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>;
 }

package/dist/services/kokimoki-i18n.js

@@ -14,7 +14,7 @@ import { getKmEnv } from "../utils/kokimoki-env";
  * - 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
+ * - AI-powered translation requests and status polling
  *
  * Access via `kmClient.i18n`
  *
@@ -28,16 +28,20 @@ import { getKmEnv } from "../utils/kokimoki-env";
  * });
  *
  * // Initialize with primary language
- * await kmClient.i18n.init('en');
+ * await kmClient.i18n.init();
  *
  * // 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');
+ * // Poll until ready
+ * const checkInterval = setInterval(async () => {
+ *  const status = await kmClient.i18n.getTranslationStatus('de');
+ *  if (status.status === 'available') {
+ *    clearInterval(checkInterval);
+ *    // Now safe to switch language
+ *    i18next.changeLanguage('de');
+ *  }
+ * }, 2000);
  * ```
  */
 export class KokimokiI18nService {
@@ -124,23 +128,31 @@ export class KokimokiI18nService {
         const namespaces = env.i18nNamespaces ?? [];
         const fallbackLng = this.options.fallbackLng ?? language;
         const defaultNS = this.options.defaultNS;
-        this.initPromise = this.instance.init({
-            lng: language,
-            fallbackLng,
-            ns: namespaces,
-            defaultNS,
-            // Wait for backend to load translations before resolving
-            initImmediate: false,
-            backend: {
-                // i18next-http-backend passes lng as array, extract first element
-                loadPath: (lngs, ns) => {
-                    const lang = Array.isArray(lngs) ? lngs[0] : lngs;
-                    return this.getNamespaceUrl(lang, ns);
+        // Wrap in a proper Promise to ensure we wait for backend loading
+        this.initPromise = new Promise((resolve, reject) => {
+            this.instance.init({
+                lng: language,
+                fallbackLng,
+                ns: namespaces,
+                defaultNS,
+                backend: {
+                    // i18next-http-backend passes lng as array, extract first element
+                    loadPath: (lngs, ns) => {
+                        const lang = Array.isArray(lngs) ? lngs[0] : lngs;
+                        return this.getNamespaceUrl(lang, ns);
+                    },
+                },
+                interpolation: {
+                    escapeValue: false,
                 },
-            },
-            interpolation: {
-                escapeValue: false,
-            },
+            }, (err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
         });
         return this.initPromise;
     }
@@ -200,22 +212,31 @@ export class KokimokiI18nService {
         return getKmEnv().i18nLanguages ?? [];
     }
     /**
-     * Get the status of all languages that have been requested for AI translation.
+     * Request AI translation for a target language.
      *
-     * @returns Promise with array of language statuses
+     * 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 translation status
      *
      * @example
      * ```typescript
-     * const { languages } = await kmClient.i18n.getAllLanguagesStatus();
-     * // [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
+     * const status = await kmClient.i18n.requestTranslation('de');
+     *
+     * if (status === 'available') {
+     *   // Already translated, switch immediately
+     *   i18next.changeLanguage('de');
+     * }
      * ```
      */
-    async getAllLanguagesStatus() {
-        const res = await fetch(`${this.client.apiUrl}/i18n`, {
-            method: "GET",
+    async requestTranslation(lng) {
+        const res = await fetch(`${this.client.apiUrl}/i18n/${encodeURIComponent(lng)}/translate`, {
+            method: "POST",
             headers: this.client.apiHeaders,
         });
-        return await res.json();
+        const { status } = await res.json();
+        return status;
     }
     /**
      * Get the translation status for a specific language.
@@ -244,89 +265,7 @@ export class KokimokiI18nService {
             method: "GET",
             headers: this.client.apiHeaders,
         });
-        return await res.json();
-    }
-    /**
-     * 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');
-     * }
-     * ```
-     */
-    async requestTranslation(lng) {
-        const res = await fetch(`${this.client.apiUrl}/i18n/${encodeURIComponent(lng)}/translate`, {
-            method: "POST",
-            headers: this.client.apiHeaders,
-        });
-        const data = await res.json();
-        return { lng, ...data };
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async pollTranslation(lng, options) {
-        const pollInterval = Math.max(1000, options?.pollInterval ?? 2000);
-        const timeout = options?.timeout ?? 120000;
-        const startTime = Date.now();
-        while (true) {
-            const status = await this.getTranslationStatus(lng);
-            // Call progress callback
-            options?.onProgress?.(status);
-            if (status.status === "available") {
-                return;
-            }
-            // Check for failed namespaces
-            const failedNamespaces = Object.entries(status.namespaces)
-                .filter(([_, ns]) => ns === "failed")
-                .map(([name]) => name);
-            if (failedNamespaces.length > 0) {
-                throw new Error(`Translation failed for namespaces: ${failedNamespaces.join(", ")}`);
-            }
-            // Check timeout
-            if (Date.now() - startTime > timeout) {
-                throw new Error(`Translation timed out after ${timeout}ms`);
-            }
-            // Wait before next poll
-            await new Promise((resolve) => setTimeout(resolve, pollInterval));
-        }
+        const { status } = await res.json();
+        return status;
     }
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_APP_VERSION = "3.1.1";
+export declare const KOKIMOKI_APP_VERSION = "3.1.3";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated file. Do not edit manually.
-export const KOKIMOKI_APP_VERSION = '3.1.1';
+export const KOKIMOKI_APP_VERSION = '3.1.3';

package/docs/kokimoki-ai.instructions.md

@@ -6,8 +6,7 @@ applyTo: "**/*.ts,**/*.tsx"
 # AI Integration
 
 Built-in methods for AI text generation and image transformation. No API keys required.
-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.
+All generation methods are **async job-based** - they submit a job and return immediately with a `jobId`. Use `getJob()` to poll for the result.
 
 For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
 
@@ -19,7 +18,7 @@ Access AI API via `kmClient.ai`.
 - Text generation with configurable creativity (temperature)
 - Structured JSON output with Zod schema validation
 - AI-powered image generation and modification
-- Job-based async processing with polling support
+- Job-based async processing
 - Resumable after page reload (persist jobId)
 
 ## Available Models
@@ -45,7 +44,7 @@ Access AI API via `kmClient.ai`.
 
 ### ai.generateText(req): Promise<{ jobId: string }>
 
-Submits a text generation job. Use `pollText()` to wait for the result.
+Submits a text generation job. Use `getJob()` to poll the result.
 
 **Parameters:**
 
@@ -67,12 +66,13 @@ const { jobId } = await kmClient.ai.generateText({
 });
 
 // Poll for result
-const text = await kmClient.ai.pollText(jobId);
+const job = await kmClient.ai.getJob<string>(jobId);
+console.log("Generated quest:", job.result);
 ```
 
 ### ai.generateJson<T>(req): Promise<{ jobId: string }>
 
-Submits a JSON generation job with Zod schema validation. Use `pollJson()` to wait for the result with type inference.
+Submits a JSON generation job with Zod schema validation. Use `getJob<T>()` to wait for the result with type inference.
 
 **Parameters:**
 
@@ -107,8 +107,8 @@ const { jobId } = await kmClient.ai.generateJson({
 await saveJobId(jobId);
 
 // Poll with schema for type inference and validation
-const enemy = await kmClient.ai.pollJson(jobId, { schema: enemySchema });
-console.log(enemy.name, enemy.health); // Fully typed!
+const enemy = await kmClient.ai.getJob<Enemy>(jobId);
+console.log(enemy.result?.name, enemy.result?.health); // Fully typed!
 ```
 
 ```typescript
@@ -127,13 +127,13 @@ const { jobId } = await kmClient.ai.generateJson({
   prompt: "Create 5 history quiz questions with 4 options each",
 });
 
-const questions = await kmClient.ai.pollJson(jobId, { schema: questionSchema });
-questions.forEach((q) => console.log(q.question));
+const questions = await kmClient.ai.getJob<typeof questionSchema>(jobId);
+questions.result?.forEach((q) => console.log(q.question));
 ```
 
 ### ai.generateImage(req): Promise<{ jobId: string }>
 
-Submits an image generation/modification job. Use `pollImage()` to wait for the result.
+Submits an image generation/modification job. Use `getJob()` to wait for the result.
 The result is stored as `Upload` object (see [Storage](./kokimoki-storage.instructions.md)).
 
 **Parameters:**
@@ -152,8 +152,8 @@ const { jobId } = await kmClient.ai.generateImage({
   tags: ["background", "ai-generated"],
 });
 
-const upload = await kmClient.ai.pollImage(jobId);
-console.log(upload.url); // CDN URL to the generated image
+const job = await kmClient.ai.getJob<string>(jobId);
+console.log("Generated image:", job.result); // CDN URL to the generated image
 ```
 
 ```typescript
@@ -164,12 +164,13 @@ const { jobId } = await kmClient.ai.generateImage({
   tags: ["art", "ai-generated"],
 });
 
-const upload: Upload = await kmClient.ai.pollImage(jobId);
+const job = await kmClient.ai.getJob<string>(jobId);
+console.log("Generated image:", job.result); // CDN URL to the generated image
 ```
 
 ### ai.getJob(jobId): Promise<AiJob>
 
-Get the current status of an AI job without polling.
+Get the current status of an AI job.
 
 **Parameters:**
 
@@ -199,68 +200,6 @@ if (job.status === "completed") {
 }
 ```
 
-### ai.pollText(jobId, options?): Promise<string>
-
-Poll a text generation job until completion.
-
-**Parameters:**
-
-- **jobId**: `string` The job ID to poll
-- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
-- **options.timeout**: `number` Timeout in ms (default: 120000)
-- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
-
-**Example:**
-
-```typescript
-const text = await kmClient.ai.pollText(jobId, {
-  timeout: 60000,
-  onProgress: (status) => console.log("Status:", status),
-});
-```
-
-### ai.pollJson<T>(jobId, options): Promise<T>
-
-Poll a JSON generation job until completion with schema validation.
-
-**Parameters:**
-
-- **jobId**: `string` The job ID to poll
-- **options.schema**: `ZodType` Zod schema for validation and type inference (required)
-- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
-- **options.timeout**: `number` Timeout in ms (default: 120000)
-- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
-
-**Example:**
-
-```typescript
-const enemy = await kmClient.ai.pollJson(jobId, {
-  schema: enemySchema,
-  timeout: 60000,
-  onProgress: (status) => console.log("Status:", status),
-});
-```
-
-### ai.pollImage(jobId, options?): Promise<Upload>
-
-Poll an image generation job until completion.
-
-**Parameters:**
-
-- **jobId**: `string` The job ID to poll
-- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
-- **options.timeout**: `number` Timeout in ms (default: 120000)
-- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
-
-**Example:**
-
-```typescript
-const upload = await kmClient.ai.pollImage(jobId, {
-  timeout: 60000,
-  onProgress: (status) => console.log("Status:", status),
-});
-```
-
 ## Common Patterns
 
 ### Example: Persist Jobs Across Page Reloads
@@ -297,20 +236,24 @@ const { jobId } = await kmClient.ai.generateText({
   prompt: "Write a story",
 });
 
-const text = await kmClient.ai.pollText(jobId, {
-  onProgress: (status) => {
-    if (status === "queued") setLoadingText("Waiting in queue...");
-    if (status === "processing") setLoadingText("Generating...");
-  },
-});
-setLoading(false);
+const checkInterval = setInterval(async () => {
+  const job = await kmClient.ai.getJob<string>(jobId);
+  if (job.status === "completed") {
+    console.log("Generated text:", job.result);
+    clearInterval(checkInterval);
+    setLoading(false);
+  } else if (job.status === "failed") {
+    console.error("AI generation failed:", job.error);
+    clearInterval(checkInterval);
+    setLoading(false);
+  }
+}, 2000);
 ```
 
 ## Key Points
 
-- **Job-based**: All generation methods return `{ jobId }` immediately, use poll methods for results
+- **Job-based**: All generation methods return `{ jobId }` immediately, use `getJob()` to poll for results
 - **Resumable**: Save `jobId` to store to resume polling after page reload
 - **Zod Schemas**: Use Zod schemas for `generateJson` to get automatic type inference and validation
 - **Temperature**: Range 0.0 (factual) to 1.0 (creative)
-- **Polling Options**: Configure `pollInterval`, `timeout`, and `onProgress` callback
 - **Image URLs**: Gemini models support multimodal input via `imageUrls` parameter

package/docs/kokimoki-i18n.instructions.md

@@ -110,36 +110,12 @@ const url = kmClient.i18n.getNamespaceUrl("en", "game");
 
 ## AI Translation API
 
-### i18n.getAllLanguagesStatus(): Promise<AllLanguagesStatus>
-
-Get the status of all languages that have been requested for AI translation.
-
-```typescript
-interface AllLanguagesStatus {
-  languages: { lng: string; status: LanguageStatus }[];
-}
-
-type LanguageStatus = "available" | "processing" | "failed" | "partial";
-```
-
-**Example:**
-
-```typescript
-const { languages } = await kmClient.i18n.getAllLanguagesStatus();
-// [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
-```
-
-### i18n.getTranslationStatus(lng): Promise<TranslationStatus>
+### i18n.getTranslationStatus(lng): Promise<{ status: TranslationStatus }>
 
 Get the translation status for a specific language.
 
 ```typescript
-interface TranslationStatus {
-  status: "available" | "processing" | "not_available";
-  namespaces: Record<string, NamespaceStatus>;
-}
-
-type NamespaceStatus = "available" | "processing" | "failed" | "not_available";
+type TranslationStatus = "available" | "processing" | "failed";
 ```
 
 **Example:**
@@ -147,117 +123,34 @@ type NamespaceStatus = "available" | "processing" | "failed" | "not_available";
 ```typescript
 const status = await kmClient.i18n.getTranslationStatus("de");
 
-if (status.status === "available") {
+if (status === "available") {
   i18next.changeLanguage("de");
-} else if (status.status === "processing") {
-  // Show loading indicator
-} else {
-  // Request translation
-  await kmClient.i18n.requestTranslation("de");
 }
 ```
 
-### i18n.requestTranslation(lng): Promise<RequestTranslationResult>
+### i18n.requestTranslation(lng): Promise<TranslationStatus>
 
 Request AI translation for a target language. Triggers background AI translation jobs for all namespaces.
 
 ```typescript
-interface RequestTranslationResult {
-  lng: string;
-  status: "started" | "already_processing" | "already_available";
-}
+type TranslationStatus = "available" | "processing" | "failed";
 ```
 
 **Example:**
 
 ```typescript
-const result = await kmClient.i18n.requestTranslation("de");
+const status = await kmClient.i18n.requestTranslation("de");
 
-if (result.status === "already_available") {
+if (status === "already_available") {
   // Already translated, switch immediately
   i18next.changeLanguage("de");
 } else {
-  // Poll until ready
-  await kmClient.i18n.pollTranslation("de");
-  i18next.changeLanguage("de");
+  // Poll until ready using getTranslationStatus
 }
 ```
 
-### i18n.pollTranslation(lng, options?): Promise<void>
-
-Poll a translation request until all namespaces are available.
-
-**Parameters:**
-
-- **lng**: `string` Language code to poll for
-- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
-- **options.timeout**: `number` Timeout in ms (default: 120000)
-- **options.onProgress**: `(status: TranslationStatus) => void` Progress callback
-
-**Example:**
-
-```typescript
-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");
-```
-
 ## Common Patterns
 
-### Example: Language Switcher with AI Translation
-
-```tsx
-import { useState } from "react";
-import { useTranslation } from "react-i18next";
-import { getKmClient } from "@kokimoki/app";
-
-const kmClient = getKmClient();
-
-const LanguageSwitcher = () => {
-  const { i18n } = useTranslation();
-  const [loading, setLoading] = useState(false);
-
-  const switchLanguage = async (lng: string) => {
-    // Check if translation is available
-    const status = await kmClient.i18n.getTranslationStatus(lng);
-
-    if (status.status === "available") {
-      i18n.changeLanguage(lng);
-      return;
-    }
-
-    // Request and wait for AI translation
-    setLoading(true);
-    await kmClient.i18n.requestTranslation(lng);
-    await kmClient.i18n.pollTranslation(lng, {
-      onProgress: (s) => console.log(`Translating: ${s.status}`),
-    });
-    setLoading(false);
-
-    i18n.changeLanguage(lng);
-  };
-
-  return (
-    <select
-      value={i18n.language}
-      onChange={(e) => switchLanguage(e.target.value)}
-      disabled={loading}
-    >
-      <option value="en">English</option>
-      <option value="de">Deutsch</option>
-      <option value="fr">Français</option>
-    </select>
-  );
-};
-```
-
 ### Example: Using Translations in Components
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/app",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",