@kokimoki/app 2.1.1 → 3.0.0

package/dist/protocol/ws-message/reader.d.ts

@@ -6,6 +6,6 @@ export declare class WsMessageReader {
     readInt32(): number;
     readUint32(): number;
     readString(): string;
-    readUint8Array(): Uint8Array<ArrayBuffer>;
+    readUint8Array(): Uint8Array;
     get end(): boolean;
 }

package/dist/services/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./kokimoki-ai";
+export * from "./kokimoki-i18n";
 export * from "./kokimoki-leaderboard";
 export * from "./kokimoki-storage";

package/dist/services/index.js

@@ -1,3 +1,4 @@
 export * from "./kokimoki-ai";
+export * from "./kokimoki-i18n";
 export * from "./kokimoki-leaderboard";
 export * from "./kokimoki-storage";

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

@@ -1,17 +1,74 @@
+import { z, ZodType } from "zod/v4";
 import { KokimokiClient } from "../core";
-import type { Upload } from "../types";
+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 {
+    jobId: string;
+    type: AiJobType;
+    status: AiJobStatus;
+    result?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    createdAt: number;
+}
+/** AI model options */
+type AiModel = "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";
+/** Image generation model options */
+type ImageModel = "gemini-2.5-flash-image" | "gemini-3-pro-image-preview";
+/** Common request options for text generation */
+interface TextGenerateRequest {
+    model?: AiModel;
+    /** System prompt that sets the behavior and context for the AI */
+    systemPrompt?: string;
+    /** The user's message or question to send to the AI */
+    prompt: string;
+    /** Controls randomness in the response (0.0 to 1.0) */
+    temperature?: number;
+    /** Image URLs to include with the prompt (Gemini models only) */
+    imageUrls?: string[];
+}
+/** Request options for JSON generation */
+interface JsonGenerateRequest<T extends ZodType> extends Omit<TextGenerateRequest, "prompt"> {
+    /** Zod schema that defines the expected JSON structure */
+    schema: T;
+    /** The user's message or question to send to the AI */
+    prompt: string;
+}
+/** Request options for image generation */
+interface ImageGenerateRequest {
+    model?: ImageModel;
+    /** The prompt describing the image modification */
+    prompt: string;
+    /** Image URLs to include in the generation */
+    imageUrls?: string[];
+    /** Tags to associate with the generated image */
+    tags?: string[];
+}
+/** Job submission response */
+interface JobSubmitResponse {
+    jobId: string;
+    status: AiJobStatus;
+}
 /**
  * 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)
@@ -25,145 +82,149 @@ import type { Upload } from "../types";
  *
  * @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 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.
+     * 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);
      * ```
      */
-    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;
-    }>;
+    generateText(req: TextGenerateRequest): Promise<JobSubmitResponse>;
     /**
      * 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 });
+     * ```
+     */
+    generateJson<T extends ZodType>(req: JsonGenerateRequest<T>): Promise<JobSubmitResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    generateImage(req: ImageGenerateRequest): Promise<JobSubmitResponse>;
+    /**
+     * 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.
+     */
+    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.
      */
-    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>;
+    pollImage(jobId: string, options?: PollOptions<AiJobStatus>): Promise<Upload>;
     /**
-     * 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.
+     * Internal polling implementation.
      */
-    modifyImage(baseImageUrl: string, prompt: string, tags?: string[], model?: 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview'): Promise<Upload>;
+    private pollJob;
 }
+export {};