@kokimoki/app 1.16.2 → 2.0.0

package/dist/llms.txt

@@ -0,0 +1,649 @@
+---
+description: Instructions for the Kokimoki SDK
+applyTo: '**/*.tsx,**/*.ts'
+---
+
+# Kokimoki SDK
+
+The Kokimoki SDK is a comprehensive development toolkit for building real-time collaborative game applications
+
+## General guidelines
+
+- **IMPORTANT** `kmClient` is the main entry point for Kokimoki SDK
+- Use `kmClient.id` as a unique identifier for each client (player)
+- Use `kmClient.store` for global stores and `kmClient.localStore` for local stores
+- 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 AI integration API methods: `kmClient.ai.chat`, `kmClient.ai.generateJson`, and `kmClient.ai.modifyImage` to add AI capabilities to application
+- Use leaderboard API methods: `kmClient.leaderboard.insertEntry`, `kmClient.leaderboard.upsertEntry`, `kmClient.leaderboard.listEntries`, and `kmClient.leaderboard.getBestEntry` to add leaderboard capabilities to application
+
+## Kokimoki Client
+
+- The `kmClient` instance is created in [km-client.ts](../../src/services/km-client.ts)
+- The `kmClient` provides the following key functionalities:
+  - `kmClient.store` and `kmClient.localStore` for creating stores
+  - `kmClient.transact` for atomic state updates
+  - `kmClient.serverTimestamp()` for synchronized timestamps
+  - `kmClient.id` for unique player identification
+
+## Client ID
+
+- Each client (player) has a unique `kmClient.id` (aka `clientId`), stable identifier that represents a player across multiple connections
+  (client sessions)
+- The `kmClient.id` is persistent across client connections
+- The `kmClient.id` remains consistent after user reconnect or page reload
+- Use `kmClient.id` to identify players in global stores
+- Each client (player) can have multiple connections, but all connections share the same `kmClient.id`
+
+## Kokimoki Store
+
+Kokimoki Store powered by `valtio` and `valtio-yjs` for real-time state management in Kokimoki game applications
+
+### Store initialization
+
+- Stores should be defined in `src/state/stores/`
+- Store can be created in two ways:
+  - `kmClient.localStore` is used for data stored on the player device (local)
+  - `kmClient.store` is used for data shared among all players in a game (global)
+
+**Example: Creating a Store**
+
+```typescript
+import { kmClient } from '@services/km-client';
+
+interface State {
+  title: string;
+  count: number;
+}
+
+const initialState: State = {
+  title: 'Store',
+  count: 0
+};
+
+// Initialize global store with initial state
+export const store = kmClient.store<PlayerState>('store-name', initialState);
+```
+
+### State management
+
+- State actions are functions that modify the store state by performing transactions
+- Actions should be defined in `/src/state/actions/`
+- Use async/await for all state transactions by `kmClient.transact` function for global stores
+- Transactions are atomic and ensure state consistency
+- ALWAYS update store state inside `kmClient.transact()` within action function
+- Prefer using records, not arrays: store collections as `Record<string, T>` with timestamp keys for automatic sorting and better sync performance
+
+**Example: Updating State**
+
+```typescript
+import { store } from '../store';
+
+// Update state
+await kmClient.transact([store], ([state]) => {
+  state.title = 'New store';
+  state.count += 1;
+});
+```
+
+### Combining Stores
+
+- Multiple stores can be updated in a single transaction
+- Prefer to update stores in a single transaction to ensure state consistency
+
+**Example: Multiple Stores**
+
+```typescript
+// Update multiple stores in a single transaction
+await kmClient.transact([store1, store2], ([state1, state2]) => {
+  state1.name = 'My Store1';
+  state2.name = 'My Store2';
+});
+```
+
+### Reactive State in Components
+
+- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- The component will re-render when the store state changes
+
+**Example: Using State in Components**
+
+```tsx
+import { useSnapshot } from 'valtio';
+import { store } from '../store';
+
+const Component = () => {
+  // Get reactive snapshot of the store state
+  const { title, count } = useSnapshot(store.proxy);
+
+  return (
+    <div>
+      <h1>Title: {title}</h1>
+      <p>Count: {count}</p>
+    </div>
+  );
+};
+```
+
+## Server Time Synchronization
+
+Kokimoki SDK implements a time synchronization system to ensure consistent timestamps across all connected clients, regardless of their local clock differences
+
+- Use `kmClient.serverTimestamp()` to get the current server-synchronized timestamp
+- The timestamp is a Epoch Unix Timestamp
+- Use server timestamps for time-related matters like event scheduling, timeouts, timers, etc.
+
+## Storage
+
+Kokimoki SDK provides a storage service for uploading and managing files. Commonly used for media files (images, videos, audio), but also supports other file types like JSON or text files that aren't suitable for real-time stores. No setup required.
+
+Access storage API via `kmClient.storage`.
+
+### API Methods
+
+#### storage.upload(name, blob, tags?): Promise<Upload>
+
+Uploads a file to storage.
+
+**Parameters:**
+
+- **name**: `string` filename
+- **blob**: `Blob` object to upload
+- **tags**: `string[]` (optional, default: [])
+
+**Example:**
+
+```typescript
+const upload: Upload = await kmClient.storage.upload('filename.jpg', fileBlob, [
+  'tag1',
+  'tag2'
+]);
+// Use upload.url to access the media file
+```
+
+#### storage.listUploads(filter?, skip?, limit?): Promise<Paginated<Upload>>
+
+Query uploaded files by filter and pagination
+
+**Parameters:**
+
+- **filter.clientId**: `string` Specific client (optional)
+- **filter.mimeTypes**: `string[]` E.g., ['image/jpeg', 'image/png'] (optional)
+- **filter.tags**: `string[]` All tags must match (optional)
+- **skip**: `number` Pagination offset (default: 0)
+- **limit**: `number` Max results (default: 100)
+
+**Example:**
+
+```typescript
+// Query uploads by tag and uploaded by this client
+const { items, total } = await kmClient.storage.listUploads(
+  { clientId: kmClient.id, tags: ['tag1'] },
+  skip,
+  limit
+);
+```
+
+#### storage.updateUpload(id, update): Promise<Upload>
+
+Replace uploaded file tags with new tags
+
+**Parameters:**
+
+- **id**: `string` Upload id
+- **update.tags**: `string[]` (optional)
+
+**Example:**
+
+```typescript
+const updatedUpload: Upload = await kmClient.storage.updateUpload(upload.id, {
+  tags: ['new']
+});
+```
+
+#### storage.deleteUpload(id): Promise<{ acknowledged: boolean; deletedCount: number }>
+
+Permanently delete uploaded file
+
+**Parameters:**
+
+- **id**: `string` Upload id
+
+**Example:**
+
+```typescript
+await kmClient.storage.deleteUpload(upload.id);
+```
+
+### Types
+
+```typescript
+interface Upload {
+  id: string; // unique id
+  url: string; // file url (CDN)
+  name: string; // original filename
+  size: number; // in bytes
+  mimeType: string;
+  clientId: string; // who uploaded
+  tags: string[]; // metadata for filtering and organization
+  completed: boolean; // upload status
+  createdAt: Date;
+  appId: string;
+}
+
+interface Paginated<T> {
+  items: T[];
+  total: number;
+}
+```
+
+### Common Patterns
+
+#### Example: User-specific uploads
+
+```typescript
+// Get uploaded files by clientId
+const clientUploads = await kmClient.storage.listUploads({ clientId: kmClient.id });
+```
+
+#### Example: Filter by file type
+
+```typescript
+// Get only uploaded images
+const images = await kmClient.storage.listUploads({
+  mimeTypes: ['image/jpeg', 'image/png']
+});
+```
+
+#### Example: Tag-based uploads
+
+```typescript
+// Upload file with tag
+await kmClient.storage.upload('avatar.jpg', blob, ['profile']);
+
+// Query uploads by tag
+const profileUploads = await kmClient.storage.listUploads({ tags: ['profile'] });
+```
+
+#### Example: Usage in Kokimoki Store
+
+```typescript
+// Upload image from Blob
+const upload = await kmClient.storage.upload('file.jpg', blob);
+
+await kmClient.transact([store], (state) => {
+  // Add image to images array in the store
+  state.playerImages[upload.id] = { url: upload.url };
+});
+```
+
+### Key Points
+
+- **Use Cases**: Commonly used for media files (images, videos, audio), but also supports JSON, text files, or any data not suitable for real-time stores
+- **CDN**: File `upload.url` is public and can be used directly
+- **Tags**: Use tag system to organize uploads
+- **Pagination**: Use skip/limit to paginate results
+- **Filtering**: Combine clientId, mimeTypes, and tags to query uploads
+
+## AI Integration
+
+Built-in methods for AI text generation and image transformation. No API keys required.
+
+Access AI API via `kmClient.ai`.
+
+### API Methods
+
+#### ai.chat(req): Promise<{ content: string }>
+
+Used to generate text response with AI
+
+**Parameters:**
+
+- **req.model**: `string` AI model to use (optional). 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
+- **req.systemPrompt**: `string` AI role/behavior (optional)
+- **req.userPrompt**: `string` User message (optional)
+- **req.temperature**: `number` Creativity level from 0.0 = factual to 2.0 = creative (optional)
+- **req.maxTokens**: `number` Response length limit (optional)
+
+**Examples:**
+
+```typescript
+// Generate text response
+const { content } = await kmClient.ai.chat({
+  model: 'gemini-2.5-flash-lite',
+  systemPrompt: 'You are a sarcastic assistant',
+  userPrompt: 'Write a story about dragons',
+  temperature: 0.7, // moderate creativity
+  maxTokens: 500 // limit to 500 tokens
+});
+```
+
+#### ai.generateJson<T>(req): Promise<T>
+
+Used to generate structured JSON output with AI. Automatically ensures the response is valid JSON and parses it for you.
+
+**Parameters:**
+
+- **req.model**: `string` AI model to use (optional). 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
+- **req.systemPrompt**: `string` AI role/behavior (optional)
+- **req.userPrompt**: `string` User message (optional)
+- **req.temperature**: `number` Creativity level from 0.0 = factual to 2.0 = creative (optional)
+- **req.maxTokens**: `number` Response length limit (optional)
+
+**Returns:** Promise resolving to parsed JSON object of type T
+
+**Examples:**
+
+```typescript
+// Generate quiz questions
+interface Question {
+  question: string;
+  options: string[];
+  correctAnswer: number;
+}
+
+const questions = await kmClient.ai.generateJson<Question[]>({
+  systemPrompt: 'Generate quiz questions as JSON array',
+  userPrompt: 'Create 5 history quiz questions with 4 options each',
+  temperature: 0.7
+});
+
+// questions is already parsed and typed
+questions.forEach(q => console.log(q.question));
+```
+
+```typescript
+// Generate game character data
+interface Character {
+  name: string;
+  strength: number;
+  agility: number;
+  backstory: string;
+}
+
+const character = await kmClient.ai.generateJson<Character>({
+  userPrompt: 'Create a fantasy warrior character with stats',
+  temperature: 0.8
+});
+
+console.log(character.name, character.strength);
+```
+
+#### ai.modifyImage(baseImageUrl, prompt, tags?): Promise<Upload>
+
+Used to modify/transform image with AI. The result is stored as [`Upload`](#storage) object
+
+**Parameters:**
+
+- **baseImageUrl**: `string` Source image URL
+- **prompt**: `string` Modification/transformation description
+- **tags**: `string[]` Tags for the result in `Upload` format (optional, default: [])
+
+**Example:**
+
+```typescript
+// Modify image from url
+const upload: Upload = await kmClient.ai.modifyImage(
+  'https://static.kokimoki.com/game/image.jpg',
+  'Make it look like a painting',
+  ['art', 'ai-generated']
+);
+```
+
+## Store Connections
+
+Each Kokimoki store has a `connections` property that provides real-time presence information of all clients connected to that store.
+
+### Accessing Connections
+
+- Use `store.connections` to access the connections proxy for any Kokimoki store
+- Use `store.connections.clientIds` to get a `Set` of online client IDs
+- Use `useSnapshot` to get reactive updates when connections change
+- **ALWAYS** use `useSnapshot(store.connections)` to get reactive updates when connections change
+
+### Example: Track Online Players
+
+```tsx
+import { useSnapshot } from 'valtio';
+import { globalStore } from '@/state/stores/global-store';
+
+const Component = () => {
+  // Get online client IDs from store connections
+  const onlineClientIds = useSnapshot(globalStore.connections).clientIds;
+
+  // Check if specific player is online
+  const isPlayerOnline = onlineClientIds.has(playerId);
+
+  // Get count of online players
+  const onlineCount = onlineClientIds.size;
+
+  return <div>Online players: {onlineCount}</div>;
+};
+```
+
+### Example: Display Player List with Online Status
+
+```tsx
+import { useSnapshot } from 'valtio';
+import { globalStore } from '@/state/stores/global-store';
+
+const PlayerList = () => {
+  const players = useSnapshot(globalStore.proxy).players;
+  const onlineClientIds = useSnapshot(globalStore.connections).clientIds;
+
+  const playersList = Object.entries(players).map(([clientId, player]) => ({
+    clientId,
+    name: player.name,
+
+    isOnline: onlineClientIds.has(clientId)
+  }));
+
+  return (
+    <ul>
+      {playersList.map((player) => (
+        <li key={player.clientId}>
+          {player.name} - {player.isOnline ? 'Online' : 'Offline'}
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### Key Points
+
+- Each store has its own `connections` property
+- `connections.clientIds` is a `Set<string>` containing connected client IDs
+- Use `useSnapshot(store.connections)` to get reactive updates
+- Players can have multiple browser tabs open, but all share the same `clientId`
+- A player is considered online if their `clientId` is in the `clientIds` set
+
+## Leaderboard
+
+Kokimoki SDK provides a leaderboard system to track and display player rankings. No setup required.
+
+Access leaderboard API via `kmClient.leaderboard`.
+
+### When to Use Leaderboard API vs Global Store
+
+**Use the Leaderboard API when:**
+- You have a large number of entries (hundreds to thousands of players)
+- You need efficient ranking and sorting with database indexes
+- You want pagination and optimized queries for top scores
+- Memory and network efficiency are important
+
+**Use a Global Store when:**
+- You have a small number of players (typically under 100)
+- You need real-time updates and live leaderboard changes
+- You want to combine player scores with other game state
+- The leaderboard is temporary (session-based or reset frequently)
+
+The leaderboard API is optimized for scalability with database indexes and efficient queries, making it the better choice for games with many players. Global stores are ideal for smaller, real-time collaborative scenarios where you want immediate synchronization.
+
+### API Methods
+
+#### leaderboard.insertEntry<MetadataT, PrivateMetadataT>(leaderboardName, sortDir, score, metadata, privateMetadata): Promise<{ rank: number }>
+
+Add a new entry to a leaderboard. Creates a new entry each time it's called.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **score**: `number` The score value
+- **metadata**: `MetadataT` Public metadata visible to all players
+- **privateMetadata**: `PrivateMetadataT` Private metadata only accessible via API
+
+**Returns:** Promise resolving to an object with the entry's rank
+
+**Example:**
+
+```typescript
+const { rank } = await kmClient.leaderboard.insertEntry(
+  'high-scores',
+  'desc',
+  1500,
+  { playerName: 'Alice', level: 10 },
+  { sessionId: 'abc123' }
+);
+console.log(`New rank: ${rank}`);
+```
+
+#### leaderboard.upsertEntry<MetadataT, PrivateMetadataT>(leaderboardName, sortDir, score, metadata, privateMetadata): Promise<{ rank: number }>
+
+Add or update the latest entry for the current client in a leaderboard. Replaces the previous entry if one exists.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **score**: `number` The score value
+- **metadata**: `MetadataT` Public metadata visible to all players
+- **privateMetadata**: `PrivateMetadataT` Private metadata only accessible via API
+
+**Returns:** Promise resolving to an object with the entry's rank
+
+**Example:**
+
+```typescript
+const { rank } = await kmClient.leaderboard.upsertEntry(
+  'daily-scores',
+  'desc',
+  2000,
+  { playerName: 'Bob', completionTime: 120 },
+  { deviceId: 'xyz789' }
+);
+console.log(`Updated rank: ${rank}`);
+```
+
+#### leaderboard.listEntries<MetadataT>(leaderboardName, sortDir, skip?, limit?): Promise<Paginated<{ rank: number; score: number; metadata: MetadataT }>>
+
+List entries in a leaderboard with pagination.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **skip**: `number` Number of entries to skip for pagination (default: 0)
+- **limit**: `number` Maximum number of entries to return (default: 100)
+
+**Returns:** Promise resolving to a paginated list of entries
+
+**Example:**
+
+```typescript
+const { items, total } = await kmClient.leaderboard.listEntries(
+  'weekly-scores',
+  'desc',
+  0, // skip
+  10 // limit - get top 10
+);
+
+items.forEach(entry => {
+  console.log(`Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`);
+});
+```
+
+#### leaderboard.getBestEntry<MetadataT>(leaderboardName, sortDir, clientId?): Promise<{ rank: number; score: number; metadata: MetadataT }>
+
+Get the best entry for a specific client in a leaderboard.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **clientId**: `string` (optional) Client ID to get entry for. Defaults to current client if not provided.
+
+**Returns:** Promise resolving to the best entry for the client
+
+**Example:**
+
+```typescript
+// Get current client's best entry
+const myBest = await kmClient.leaderboard.getBestEntry('all-time-high', 'desc');
+console.log(`My best: Rank ${myBest.rank}, Score ${myBest.score}`);
+
+// Get another player's best entry
+const otherBest = await kmClient.leaderboard.getBestEntry(
+  'all-time-high',
+  'desc',
+  'other-client-id'
+);
+```
+
+### Common Patterns
+
+#### Example: Track High Scores
+
+```typescript
+// Submit a new high score
+await kmClient.leaderboard.upsertEntry(
+  'high-scores',
+  'desc',
+  score,
+  { playerName: player.name },
+  { timestamp: Date.now() }
+);
+
+// Display top 10
+const { items } = await kmClient.leaderboard.listEntries('high-scores', 'desc', 0, 10);
+```
+
+#### Example: Track Speed Run Times
+
+```typescript
+// Submit completion time (lower is better)
+await kmClient.leaderboard.upsertEntry(
+  'speed-run',
+  'asc',
+  completionTimeInSeconds,
+  { playerName: player.name, difficulty: 'hard' },
+  {}
+);
+
+// Get personal best
+const myBest = await kmClient.leaderboard.getBestEntry('speed-run', 'asc');
+```
+
+### Key Points
+
+- **Sort Direction**: Use `asc` when lower scores are better (e.g., completion time), `desc` when higher scores are better (e.g., points)
+- **Insert vs Upsert**: Use `insertEntry` to keep all attempts, `upsertEntry` to keep only the latest/best
+- **Metadata**: Public metadata is visible to all, private metadata is only accessible via API calls
+- **Pagination**: Use skip/limit to implement leaderboard pages or "load more" functionality

package/dist/message-queue.d.ts

@@ -0,0 +1,8 @@
+import { SyncedStore } from "./synced-store";
+export declare class MessageQueue<T> extends SyncedStore<{
+  messages: T[];
+}> {
+  name: string;
+  constructor(name: string);
+  push(message: T): Promise<Uint8Array>;
+}

package/dist/message-queue.js

@@ -0,0 +1,19 @@
+import EventEmitter from "events";
+import { SyncedStore } from "./synced-store";
+import Y from "yjs";
+export class MessageQueue extends SyncedStore {
+  name;
+  constructor(name) {
+    super({ messages: [] });
+    this.name = name;
+  }
+  async push(message) {
+    // Construct Y update to push the message to the queue
+    const id = crypto.randomUUID();
+    const ydoc = new Y.Doc();
+    const map = ydoc.getMap("messages");
+    map.set(id, message);
+    const update = Y.encodeStateAsUpdate(ydoc);
+    return update;
+  }
+}