@kokimoki/app 1.17.0 → 2.0.1

package/dist/services/kokimoki-leaderboard.js

@@ -0,0 +1,203 @@
+/**
+ * Kokimoki Leaderboard Service
+ *
+ * Provides efficient player ranking and score tracking with database indexes and optimized queries.
+ * Ideal for games with large numbers of players and competitive scoring.
+ *
+ * **Key Features:**
+ * - Efficient ranking with database indexes
+ * - Support for ascending (lowest-is-best) and descending (highest-is-best) sorting
+ * - Pagination for large leaderboards
+ * - Public and private metadata for entries
+ * - Insert (preserve all attempts) or upsert (keep latest only) modes
+ *
+ * **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)
+ *
+ * Access via `kmClient.leaderboard`
+ *
+ * @example
+ * ```typescript
+ * // Submit a high score
+ * const { rank } = await kmClient.leaderboard.upsertEntry(
+ *   'high-scores',
+ *   'desc',
+ *   1500,
+ *   { playerName: 'Alice' },
+ *   {}
+ * );
+ *
+ * // Get top 10
+ * const { items } = await kmClient.leaderboard.listEntries('high-scores', 'desc', 0, 10);
+ *
+ * // Get player's best
+ * const best = await kmClient.leaderboard.getBestEntry('high-scores', 'desc');
+ * ```
+ */
+export class KokimokiLeaderboardService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Add a new entry to a leaderboard.
+     *
+     * Creates a new entry each time it's called, preserving all attempts. Use this when you want
+     * to track every score submission (e.g., all game attempts).
+     *
+     * @param leaderboardName The name of the leaderboard to add the entry to
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param score The numeric score value
+     * @param metadata Public metadata visible to all players (e.g., player name, level)
+     * @param privateMetadata Private metadata only accessible via API calls (e.g., session ID)
+     * @returns A 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}`);
+     * ```
+     */
+    async insertEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                leaderboardName,
+                sortDir,
+                score,
+                metadata,
+                privateMetadata,
+                upsert: false,
+            }),
+        });
+        return await res.json();
+    }
+    /**
+     * Add or update the latest entry for the current client in a leaderboard.
+     *
+     * Replaces the previous entry if one exists for this client. Use this when you only want
+     * to keep the latest or best score per player (e.g., daily high score).
+     *
+     * @param leaderboardName The name of the leaderboard to upsert the entry in
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param score The numeric score value
+     * @param metadata Public metadata visible to all players (e.g., player name, completion time)
+     * @param privateMetadata Private metadata only accessible via API calls (e.g., device ID)
+     * @returns A promise resolving to an object with the entry's updated rank
+     *
+     * @example
+     * ```typescript
+     * const { rank } = await kmClient.leaderboard.upsertEntry(
+     *   'daily-scores',
+     *   'desc',
+     *   2000,
+     *   { playerName: 'Bob', completionTime: 120 },
+     *   { deviceId: 'xyz789' }
+     * );
+     * console.log(`Updated rank: ${rank}`);
+     * ```
+     */
+    async upsertEntry(leaderboardName, sortDir, score, metadata, privateMetadata) {
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                leaderboardName,
+                sortDir,
+                score,
+                metadata,
+                privateMetadata,
+                upsert: true,
+            }),
+        });
+        return await res.json();
+    }
+    /**
+     * List entries in a leaderboard with pagination.
+     *
+     * Retrieves a sorted list of leaderboard entries. Use skip and limit parameters for
+     * pagination (e.g., showing top 10, or implementing "load more" functionality).
+     *
+     * @param leaderboardName The name of the leaderboard to query
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param skip Number of entries to skip for pagination (default: 0)
+     * @param limit Maximum number of entries to return (default: 100)
+     * @returns A promise resolving to a paginated list of entries with rank, score, and metadata
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 scores
+     * const { items, total } = await kmClient.leaderboard.listEntries(
+     *   'weekly-scores',
+     *   'desc',
+     *   0,
+     *   10
+     * );
+     *
+     * items.forEach(entry => {
+     *   console.log(`Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`);
+     * });
+     * ```
+     */
+    async listEntries(leaderboardName, sortDir, skip = 0, limit = 100) {
+        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&skip=${skip}&limit=${limit}`, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Get the best entry for a specific client in a leaderboard.
+     *
+     * Retrieves the highest-ranked entry for a client based on the sort direction.
+     * Defaults to the current client if no clientId is provided.
+     *
+     * @param leaderboardName The name of the leaderboard to query
+     * @param sortDir Sort direction: "asc" for lowest-is-best (e.g., completion time),
+     *                "desc" for highest-is-best (e.g., points)
+     * @param clientId The client ID to get the best entry for (optional, defaults to current client)
+     * @returns A promise resolving to the best entry with rank, score, and metadata
+     *
+     * @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'
+     * );
+     * ```
+     */
+    async getBestEntry(leaderboardName, sortDir, clientId) {
+        const encodedLeaderboardName = encodeURIComponent(leaderboardName);
+        const res = await fetch(`${this.client.apiUrl}/leaderboard-entries/best?leaderboardName=${encodedLeaderboardName}&sortDir=${sortDir}&clientId=${clientId || this.client.id}`, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+}

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

@@ -0,0 +1,155 @@
+import { KokimokiClient } from "../core";
+import type { Paginated, Upload } from "../types";
+/**
+ * Kokimoki Storage Service
+ *
+ * Provides file upload and management capabilities for game applications. Ideal for media files
+ * (images, videos, audio) and other data not suitable for real-time stores (JSON, text files).
+ *
+ * **Key Features:**
+ * - Upload files to cloud storage with CDN delivery
+ * - Tag-based organization and filtering
+ * - Query uploads by client, MIME type, or tags
+ * - Pagination support for large collections
+ * - Public CDN URLs for direct access
+ *
+ * **Common Use Cases:**
+ * - Player avatars and profile images
+ * - Game screenshots and replays
+ * - User-generated content
+ * - Asset uploads (levels, maps, custom skins)
+ * - JSON configuration files
+ *
+ * Access via `kmClient.storage`
+ *
+ * @example
+ * ```typescript
+ * // Upload an image
+ * const upload = await kmClient.storage.upload('avatar.jpg', imageBlob, ['profile']);
+ *
+ * // Query user's uploads
+ * const myUploads = await kmClient.storage.listUploads({
+ *   clientId: kmClient.id
+ * });
+ *
+ * // Use in store
+ * await kmClient.transact([store], (state) => {
+ *   state.playerAvatar = upload.url;
+ * });
+ * ```
+ */
+export declare class KokimokiStorageService {
+    private readonly client;
+    constructor(client: KokimokiClient);
+    private createUpload;
+    private uploadChunks;
+    private completeUpload;
+    /**
+     * Upload a file to cloud storage.
+     *
+     * Uploads a file (Blob) to Kokimoki storage and returns an Upload object with a public CDN URL.
+     * Files are automatically chunked for efficient upload. The returned URL can be used directly
+     * in your application (e.g., in img tags or store state).
+     *
+     * @param name The filename for the upload
+     * @param blob The Blob object containing the file data
+     * @param tags Optional array of tags for organizing and filtering uploads (default: [])
+     * @returns A promise resolving to the Upload object with CDN URL and metadata
+     *
+     * @example
+     * ```typescript
+     * // Upload image with tags
+     * const upload = await kmClient.storage.upload(
+     *   'avatar.jpg',
+     *   imageBlob,
+     *   ['profile', 'avatar']
+     * );
+     *
+     * // Use the CDN URL
+     * console.log(upload.url); // https://cdn.kokimoki.com/...
+     *
+     * // Store in game state
+     * await kmClient.transact([store], (state) => {
+     *   state.players[kmClient.id].avatar = upload.url;
+     * });
+     * ```
+     */
+    upload(name: string, blob: Blob, tags?: string[]): Promise<Upload>;
+    /**
+     * Update metadata for an existing upload.
+     *
+     * Allows you to replace the tags associated with an upload. Useful for reorganizing
+     * or recategorizing uploaded files.
+     *
+     * @param id The upload ID to update
+     * @param update Object containing the new tags array
+     * @returns A promise resolving to the updated Upload object
+     *
+     * @example
+     * ```typescript
+     * // Update tags
+     * const updated = await kmClient.storage.updateUpload(upload.id, {
+     *   tags: ['archived', 'old-profile']
+     * });
+     * ```
+     */
+    updateUpload(id: string, update: {
+        tags?: string[];
+    }): Promise<Upload>;
+    /**
+     * Query uploaded files with filtering and pagination.
+     *
+     * Retrieves a list of uploads matching the specified criteria. Supports filtering by
+     * client (uploader), MIME types, and tags. Use pagination for large collections.
+     *
+     * @param filter Optional filter criteria
+     * @param filter.clientId Filter by uploader's client ID
+     * @param filter.mimeTypes Filter by MIME types (e.g., ['image/jpeg', 'image/png'])
+     * @param filter.tags Filter by tags (all specified tags must match)
+     * @param skip Number of results to skip for pagination (default: 0)
+     * @param limit Maximum number of results to return (default: 100)
+     * @returns A promise resolving to paginated Upload results with total count
+     *
+     * @example
+     * ```typescript
+     * // Get current user's images
+     * const myImages = await kmClient.storage.listUploads({
+     *   clientId: kmClient.id,
+     *   mimeTypes: ['image/jpeg', 'image/png']
+     * });
+     *
+     * // Get all profile avatars
+     * const avatars = await kmClient.storage.listUploads({
+     *   tags: ['profile', 'avatar']
+     * });
+     *
+     * // Pagination
+     * const page2 = await kmClient.storage.listUploads({}, 10, 10);
+     * ```
+     */
+    listUploads(filter?: {
+        clientId?: string;
+        mimeTypes?: string[];
+        tags?: string[];
+    }, skip?: number, limit?: number): Promise<Paginated<Upload>>;
+    /**
+     * Permanently delete an uploaded file.
+     *
+     * Removes the file from cloud storage and the CDN. The URL will no longer be accessible.
+     * This operation cannot be undone.
+     *
+     * @param id The upload ID to delete
+     * @returns A promise resolving to deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * // Delete an upload
+     * const result = await kmClient.storage.deleteUpload(upload.id);
+     * console.log(`Deleted: ${result.deletedCount} file(s)`);
+     * ```
+     */
+    deleteUpload(id: string): Promise<{
+        acknowledged: boolean;
+        deletedCount: number;
+    }>;
+}

package/dist/services/kokimoki-storage.js

@@ -0,0 +1,208 @@
+/**
+ * Kokimoki Storage Service
+ *
+ * Provides file upload and management capabilities for game applications. Ideal for media files
+ * (images, videos, audio) and other data not suitable for real-time stores (JSON, text files).
+ *
+ * **Key Features:**
+ * - Upload files to cloud storage with CDN delivery
+ * - Tag-based organization and filtering
+ * - Query uploads by client, MIME type, or tags
+ * - Pagination support for large collections
+ * - Public CDN URLs for direct access
+ *
+ * **Common Use Cases:**
+ * - Player avatars and profile images
+ * - Game screenshots and replays
+ * - User-generated content
+ * - Asset uploads (levels, maps, custom skins)
+ * - JSON configuration files
+ *
+ * Access via `kmClient.storage`
+ *
+ * @example
+ * ```typescript
+ * // Upload an image
+ * const upload = await kmClient.storage.upload('avatar.jpg', imageBlob, ['profile']);
+ *
+ * // Query user's uploads
+ * const myUploads = await kmClient.storage.listUploads({
+ *   clientId: kmClient.id
+ * });
+ *
+ * // Use in store
+ * await kmClient.transact([store], (state) => {
+ *   state.playerAvatar = upload.url;
+ * });
+ * ```
+ */
+export class KokimokiStorageService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // Storage
+    async createUpload(name, blob, tags) {
+        const res = await fetch(`${this.client.apiUrl}/uploads`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                name,
+                size: blob.size,
+                mimeType: blob.type,
+                tags,
+            }),
+        });
+        return await res.json();
+    }
+    async uploadChunks(blob, chunkSize, signedUrls) {
+        return await Promise.all(signedUrls.map(async (url, index) => {
+            const start = index * chunkSize;
+            const end = Math.min(start + chunkSize, blob.size);
+            const chunk = blob.slice(start, end);
+            const res = await fetch(url, { method: "PUT", body: chunk });
+            return JSON.parse(res.headers.get("ETag") || '""');
+        }));
+    }
+    async completeUpload(id, etags) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "PUT",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({ etags }),
+        });
+        return await res.json();
+    }
+    /**
+     * Upload a file to cloud storage.
+     *
+     * Uploads a file (Blob) to Kokimoki storage and returns an Upload object with a public CDN URL.
+     * Files are automatically chunked for efficient upload. The returned URL can be used directly
+     * in your application (e.g., in img tags or store state).
+     *
+     * @param name The filename for the upload
+     * @param blob The Blob object containing the file data
+     * @param tags Optional array of tags for organizing and filtering uploads (default: [])
+     * @returns A promise resolving to the Upload object with CDN URL and metadata
+     *
+     * @example
+     * ```typescript
+     * // Upload image with tags
+     * const upload = await kmClient.storage.upload(
+     *   'avatar.jpg',
+     *   imageBlob,
+     *   ['profile', 'avatar']
+     * );
+     *
+     * // Use the CDN URL
+     * console.log(upload.url); // https://cdn.kokimoki.com/...
+     *
+     * // Store in game state
+     * await kmClient.transact([store], (state) => {
+     *   state.players[kmClient.id].avatar = upload.url;
+     * });
+     * ```
+     */
+    async upload(name, blob, tags = []) {
+        const { id, chunkSize, urls } = await this.createUpload(name, blob, tags);
+        const etags = await this.uploadChunks(blob, chunkSize, urls);
+        return await this.completeUpload(id, etags);
+    }
+    /**
+     * Update metadata for an existing upload.
+     *
+     * Allows you to replace the tags associated with an upload. Useful for reorganizing
+     * or recategorizing uploaded files.
+     *
+     * @param id The upload ID to update
+     * @param update Object containing the new tags array
+     * @returns A promise resolving to the updated Upload object
+     *
+     * @example
+     * ```typescript
+     * // Update tags
+     * const updated = await kmClient.storage.updateUpload(upload.id, {
+     *   tags: ['archived', 'old-profile']
+     * });
+     * ```
+     */
+    async updateUpload(id, update) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "PUT",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify(update),
+        });
+        return await res.json();
+    }
+    /**
+     * Query uploaded files with filtering and pagination.
+     *
+     * Retrieves a list of uploads matching the specified criteria. Supports filtering by
+     * client (uploader), MIME types, and tags. Use pagination for large collections.
+     *
+     * @param filter Optional filter criteria
+     * @param filter.clientId Filter by uploader's client ID
+     * @param filter.mimeTypes Filter by MIME types (e.g., ['image/jpeg', 'image/png'])
+     * @param filter.tags Filter by tags (all specified tags must match)
+     * @param skip Number of results to skip for pagination (default: 0)
+     * @param limit Maximum number of results to return (default: 100)
+     * @returns A promise resolving to paginated Upload results with total count
+     *
+     * @example
+     * ```typescript
+     * // Get current user's images
+     * const myImages = await kmClient.storage.listUploads({
+     *   clientId: kmClient.id,
+     *   mimeTypes: ['image/jpeg', 'image/png']
+     * });
+     *
+     * // Get all profile avatars
+     * const avatars = await kmClient.storage.listUploads({
+     *   tags: ['profile', 'avatar']
+     * });
+     *
+     * // Pagination
+     * const page2 = await kmClient.storage.listUploads({}, 10, 10);
+     * ```
+     */
+    async listUploads(filter = {}, skip = 0, limit = 100) {
+        const url = new URL("/uploads", this.client.apiUrl);
+        url.searchParams.set("skip", skip.toString());
+        url.searchParams.set("limit", limit.toString());
+        if (filter.clientId) {
+            url.searchParams.set("clientId", filter.clientId);
+        }
+        if (filter.mimeTypes) {
+            url.searchParams.set("mimeTypes", filter.mimeTypes.join());
+        }
+        if (filter.tags) {
+            url.searchParams.set("tags", filter.tags.join());
+        }
+        const res = await fetch(url.href, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Permanently delete an uploaded file.
+     *
+     * Removes the file from cloud storage and the CDN. The URL will no longer be accessible.
+     * This operation cannot be undone.
+     *
+     * @param id The upload ID to delete
+     * @returns A promise resolving to deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * // Delete an upload
+     * const result = await kmClient.storage.deleteUpload(upload.id);
+     * console.log(`Deleted: ${result.deletedCount} file(s)`);
+     * ```
+     */
+    async deleteUpload(id) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "DELETE",
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kokimoki-local-store";
+export * from "./kokimoki-store";
+export * from "./kokimoki-transaction";

package/dist/stores/index.js

@@ -0,0 +1,3 @@
+export * from "./kokimoki-local-store";
+export * from "./kokimoki-store";
+export * from "./kokimoki-transaction";

package/dist/stores/kokimoki-local-store.d.ts

@@ -0,0 +1,11 @@
+import { KokimokiStore } from "./kokimoki-store";
+export declare class KokimokiLocalStore<T extends object> extends KokimokiStore<T> {
+    private readonly localRoomName;
+    private _stateKey?;
+    private get stateKey();
+    constructor(localRoomName: string, defaultState: T);
+    getInitialUpdate(appId: string, clientId: string): {
+        roomHash: number;
+        initialUpdate: Uint8Array<ArrayBufferLike> | undefined;
+    };
+}

package/dist/stores/kokimoki-local-store.js

@@ -0,0 +1,40 @@
+import { fingerprint32 } from "farmhash-modern";
+import * as Y from "yjs";
+import { RoomSubscriptionMode } from "../core";
+import { KokimokiStore } from "./kokimoki-store";
+export class KokimokiLocalStore extends KokimokiStore {
+    localRoomName;
+    _stateKey;
+    get stateKey() {
+        if (!this._stateKey) {
+            throw new Error("Not initialized");
+        }
+        return this._stateKey;
+    }
+    constructor(localRoomName, defaultState) {
+        super(`/l/${localRoomName}`, defaultState, RoomSubscriptionMode.ReadWrite);
+        this.localRoomName = localRoomName;
+        // Synchronize doc changes to local storage
+        // TODO: maybe do not serialize full state every time
+        this.doc.on("update", () => {
+            const value = Y.encodeStateAsUpdate(this.doc);
+            const valueString = String.fromCharCode(...value);
+            const valueBase64 = btoa(valueString);
+            localStorage.setItem(this.stateKey, valueBase64);
+        });
+    }
+    getInitialUpdate(appId, clientId) {
+        this._stateKey = `${appId}/${clientId}/${this.localRoomName}`;
+        // get initial update from local storage
+        let initialUpdate = undefined;
+        const state = localStorage.getItem(this.stateKey);
+        if (state) {
+            const valueString = atob(state);
+            initialUpdate = Uint8Array.from(valueString, (c) => c.charCodeAt(0));
+        }
+        return {
+            roomHash: fingerprint32(this.roomName),
+            initialUpdate,
+        };
+    }
+}

package/dist/stores/kokimoki-store.d.ts

@@ -0,0 +1,22 @@
+import { Snapshot } from "valtio/vanilla";
+import * as Y from "yjs";
+import { type KokimokiClient, RoomSubscriptionMode } from "../core";
+export declare class KokimokiStore<T extends object> {
+    readonly roomName: string;
+    readonly defaultValue: T;
+    readonly mode: RoomSubscriptionMode;
+    readonly doc: Y.Doc;
+    readonly proxy: T;
+    readonly docRoot: Y.Map<unknown>;
+    readonly connections: {
+        connectionIds: Set<string>;
+        clientIds: Set<string>;
+    };
+    private _unsubscribeConnectionsHandler;
+    constructor(roomName: string, defaultValue: T, mode?: RoomSubscriptionMode);
+    get(): Snapshot<T>;
+    subscribe(set: (value: Snapshot<T>) => void): () => void;
+    onJoin(client: KokimokiClient<any>): Promise<void>;
+    onBeforeLeave(_client: KokimokiClient): Promise<void>;
+    onLeave(_client: KokimokiClient): Promise<void>;
+}