@kokimoki/app 3.1.2 → 3.1.4

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:**
 
@@ -86,7 +86,7 @@ Submits a JSON generation job with Zod schema validation. Use `pollJson()` to wa
 **Example:**
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "@kokimoki/app";
 
 // Define schema with Zod
 const enemySchema = z.object({
@@ -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,73 +200,13 @@ 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
 
 ```typescript
+import { snapshot } from "@kokimoki/app";
+
 // Store jobId in local store for persistence
 const { jobId } = await kmClient.ai.generateJson({
   schema: questSchema,
@@ -277,7 +218,7 @@ await kmClient.transact([localStore], ([state]) => {
 });
 
 // On page load, resume polling if job is pending
-const pendingJobId = localStore.proxy.pendingQuestJobId;
+const pendingJobId = snapshot(localStore.proxy).pendingQuestJobId;
 if (pendingJobId) {
   const quest = await kmClient.ai.pollJson(pendingJobId, {
     schema: questSchema,
@@ -297,20 +238,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-dynamic-stores.instructions.md

@@ -133,7 +133,7 @@ export function useDynamicStore<T extends object>(
 ## Basic Usage
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { useDynamicStore } from "@/hooks/useDynamicStore";
 
 interface RoomState {
@@ -350,7 +350,7 @@ const BreakoutRoom = ({ roomId }: { roomId: string }) => {
 
 ## File Organization
 
-**ALWAYS** organize dynamic store code using the standard store/actions pattern:
+**ALWAYS** organize dynamic store code using the standard state/actions pattern:
 
 **State definition** (`src/state/chat-store.ts`):
 
@@ -408,7 +408,7 @@ export const chatActions = {
 **Usage in component** (`src/views/chat-view.tsx`):
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { useDynamicStore } from "@/hooks/useDynamicStore";
 import { createChatState, type ChatState } from "@/state/chat-store";
 import { chatActions } from "@/state/actions/chat-actions";

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 === "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/docs/kokimoki-sdk.instructions.md

@@ -16,7 +16,9 @@ The Kokimoki SDK is a comprehensive development toolkit for building real-time c
 - Use `kmClient.transact` for atomic state updates across single store or multiple stores
 - Use `kmClient.storage.upload` and related API methods to handle file uploads (media, JSON, etc.) in application
 - Use `kmClient.serverTimestamp()` for time-related matters as this will be synced among players
-- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- Use `useSnapshot` hook to get reactive state inside React components — import from `@kokimoki/app` (re-exports valtio)
+- Use `snapshot` function to read immutable state outside React components (in actions, event handlers, etc.) — import from `@kokimoki/app` — **NEVER** read directly from `store.proxy.field`
+- Use `z` and `ZodType` from `@kokimoki/app` for schema definitions (re-exports zod)
 - Use AI integration API methods: `kmClient.ai.generateText`, `kmClient.ai.generateJson`, and `kmClient.ai.generateImage` with corresponding poll methods for AI capabilities
 - Use i18n API methods: `kmClient.i18n.createI18n`, `kmClient.i18n.init`, and `kmClient.i18n.requestTranslation` for internationalization with AI-powered translations
 - Use leaderboard API methods: `kmClient.leaderboard.insertEntry`, `kmClient.leaderboard.upsertEntry`, `kmClient.leaderboard.listEntries`, and `kmClient.leaderboard.getBestEntry` to add leaderboard capabilities to application
@@ -118,13 +120,13 @@ await kmClient.transact([store1, store2], ([state1, state2]) => {
 
 ### Reactive State in Components
 
-- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- Use `useSnapshot` hook to get reactive state inside React components (import from `@kokimoki/app`)
 - The component will re-render when the store state changes
 
 **Example: Using State in Components**
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { store } from "../store";
 
 const Component = () => {
@@ -140,6 +142,44 @@ const Component = () => {
 };
 ```
 
+### Reading State Outside Components
+
+When reading state **outside React components** (in store actions, event handlers, initialization logic), use `snapshot()` from `@kokimoki/app` to get an immutable copy.
+**NEVER** read directly from `store.proxy` — the proxy is mutable and values can change between read and use.
+
+```typescript
+import { snapshot } from "@kokimoki/app";
+
+// WRONG — mutable proxy, value can change unexpectedly
+const value = store.proxy.someField;
+
+// CORRECT — immutable snapshot, safe to use
+const value = snapshot(store.proxy).someField;
+```
+
+**Example: Reading state in an store actions**
+
+```typescript
+import { snapshot } from "@kokimoki/app";
+
+// Action function that reads state and updates it based on conditions
+async function doSomething() {
+  const { count, completed } = snapshot(store.proxy);
+
+  if (count > 10 && !completed) {
+    await kmClient.transact([store], ([state]) => {
+      state.completed = true;
+    });
+  }
+}
+```
+
+### Common Patterns
+
+- **Inside React components** → `useSnapshot(store.proxy)` (reactive, triggers re-renders)
+- **Outside React components** → `snapshot(store.proxy)` (immutable, read-only)
+- **Writing state** → Always use `kmClient.transact()` (never assign to proxy directly)
+
 ## Dynamic Stores
 
 For room-based state isolation (teams, chat rooms, breakout rooms), see [Dynamic Stores](./kokimoki-dynamic-stores.instructions.md).
@@ -166,7 +206,7 @@ Each Kokimoki store has a `connections` property that provides real-time presenc
 ### Example: Track Online Players
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { globalStore } from "@/state/stores/global-store";
 
 const Component = () => {
@@ -186,7 +226,7 @@ const Component = () => {
 ### Example: Display Player List with Online Status
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { globalStore } from "@/state/stores/global-store";
 
 const PlayerList = () => {
@@ -231,8 +271,7 @@ Store names with the `__km/` prefix are reserved for SDK internal use. Do not cr
 ### Using App Meta
 
 ```tsx
-import { getKmClient } from "@kokimoki/app";
-import { useSnapshot } from "valtio";
+import { useSnapshot, getKmClient } from "@kokimoki/app";
 
 const kmClient = getKmClient();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/app",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",
@@ -19,17 +19,23 @@
     "prebuild": "node scripts/generate-version.js",
     "build": "tsc",
     "dev": "tsc -w",
-    "docs": "typedoc src/index.ts"
+    "docs": "typedoc src/index.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
   },
   "author": "Loquiz OÜ",
   "license": "Apache-2.0",
   "devDependencies": {
+    "eslint-config": "*",
     "@types/chai": "^4",
     "@types/mocha": "^10",
     "@types/node": "^18",
     "@types/ws": "^8.5.5",
     "bson-objectid": "^2.0.4",
     "chai": "^4",
+    "eslint": "^9.39.1",
+    "eslint-plugin-chai-friendly": "^1.1.0",
+    "eslint-plugin-valtio": "^0.8.0",
     "mocha": "^10",
     "ts-node": "^10",
     "tsx": "^4",

package/dist/fields.d.ts

@@ -1,110 +0,0 @@
-export interface FieldOptions {
-  label?: string;
-}
-export declare abstract class Field<T> {
-  readonly options: FieldOptions;
-  constructor(options: FieldOptions);
-  abstract get value(): T;
-  abstract get schema(): any;
-}
-export declare class BooleanField extends Field<boolean> {
-  value: boolean;
-  constructor(value: boolean, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: boolean;
-  };
-}
-export declare class ConstField<T extends string> extends Field<
-  string extends T ? never : T
-> {
-  value: string extends T ? never : T;
-  constructor(value: string extends T ? never : T, options?: FieldOptions);
-  get schema(): {
-    const: string extends T ? never : T;
-  };
-}
-export declare class ImageField extends Field<string> {
-  value: string;
-  constructor(value: string, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: string;
-  };
-}
-export declare class TextField extends Field<string> {
-  value: string;
-  constructor(value: string, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: string;
-  };
-}
-export declare class EnumField<T extends Record<string, string>> extends Field<
-  keyof T
-> {
-  enumValues: T;
-  value: keyof T;
-  constructor(enumValues: T, value: keyof T, options?: FieldOptions);
-  get schema(): {
-    enum: string[];
-  };
-}
-export declare class IntegerField extends Field<number> {
-  value: number;
-  constructor(value: number, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: number;
-  };
-}
-export declare class FloatField extends Field<number> {
-  value: number;
-  constructor(value: number, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: number;
-  };
-}
-export declare class FormGroup<
-  T extends Record<string, Field<any>>,
-  O extends Record<string, Field<any>>,
-> extends Field<
-  {
-    [key in keyof T]: T[key]["value"];
-  } & Partial<{
-    [key in keyof O]: O[key]["value"];
-  }>
-> {
-  requiredFields: T;
-  optionalFields: O;
-  constructor(requiredFields: T, optionalFields?: O, options?: FieldOptions);
-  get value(): {
-    [key in keyof T]: T[key]["value"];
-  } & Partial<{
-    [key in keyof O]: O[key]["value"];
-  }>;
-  get schema(): {
-    type: string;
-    properties: any;
-    required: string[];
-  };
-}
-export declare class FormArray<T> extends Field<T[]> {
-  private factory;
-  value: Field<T>["value"][];
-  constructor(
-    factory: () => Field<T>,
-    value: Field<T>["value"][],
-    options?: FieldOptions,
-  );
-  get schema(): {
-    type: string;
-    items: any;
-    default: T[];
-  };
-}
-export declare class Form<
-  R extends Record<string, Field<any>>,
-  O extends Record<string, Field<any>>,
-> extends FormGroup<R, O> {}