@kokimoki/app 1.17.0 → 2.0.0

package/dist/kokimoki-leaderboard.d.ts

@@ -0,0 +1,175 @@
+import { KokimokiClient } from "./kokimoki-client";
+import { Paginated } from "./types/common";
+/**
+ * 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 declare class KokimokiLeaderboard {
+    private readonly client;
+    constructor(client: KokimokiClient);
+    /**
+     * 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}`);
+     * ```
+     */
+    insertEntry<MetadataT, PrivateMetadataT>(leaderboardName: string, sortDir: "asc" | "desc", score: number, metadata: MetadataT, privateMetadata: PrivateMetadataT): Promise<{
+        rank: number;
+    }>;
+    /**
+     * 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}`);
+     * ```
+     */
+    upsertEntry<MetadataT, PrivateMetadataT>(leaderboardName: string, sortDir: "asc" | "desc", score: number, metadata: MetadataT, privateMetadata: PrivateMetadataT): Promise<{
+        rank: number;
+    }>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    listEntries<MetadataT>(leaderboardName: string, sortDir: "asc" | "desc", skip?: number, limit?: number): Promise<Paginated<{
+        rank: number;
+        score: number;
+        metadata: MetadataT;
+    }>>;
+    /**
+     * 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'
+     * );
+     * ```
+     */
+    getBestEntry<MetadataT>(leaderboardName: string, sortDir: "asc" | "desc", clientId?: string): Promise<{
+        rank: number;
+        score: number;
+        metadata: MetadataT;
+    }>;
+}

package/dist/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 KokimokiLeaderboard {
+    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/kokimoki-schema.d.ts

@@ -0,0 +1,113 @@
+export declare namespace KokimokiSchema {
+  abstract class Generic<T> {
+    abstract get defaultValue(): T;
+    abstract set defaultValue(value: T);
+  }
+  class Number extends Generic<number> {
+    defaultValue: number;
+    constructor(defaultValue?: number);
+  }
+  function number(defaultValue?: number): Number;
+  class String extends Generic<string> {
+    defaultValue: string;
+    constructor(defaultValue?: string);
+  }
+  function string(defaultValue?: string): String;
+  class Boolean extends Generic<boolean> {
+    defaultValue: boolean;
+    constructor(defaultValue?: boolean);
+  }
+  function boolean(defaultValue?: boolean): Boolean;
+  class Struct<Data extends Record<string, Generic<unknown>>> extends Generic<{
+    [key in keyof Data]: Data[key]["defaultValue"];
+  }> {
+    fields: Data;
+    constructor(fields: Data);
+    get defaultValue(): {
+      [key in keyof Data]: Data[key]["defaultValue"];
+    };
+    set defaultValue(value: {
+      [key in keyof Data]: Data[key]["defaultValue"];
+    });
+  }
+  function struct<Data extends Record<string, Generic<unknown>>>(
+    schema: Data,
+  ): Struct<Data>;
+  class Dict<T extends Generic<unknown>> {
+    schema: T;
+    defaultValue: {
+      [key: string]: T["defaultValue"];
+    };
+    constructor(
+      schema: T,
+      defaultValue?: {
+        [key: string]: T["defaultValue"];
+      },
+    );
+  }
+  function dict<T extends Generic<unknown>>(
+    schema: T,
+    defaultValue?: {
+      [key: string]: T["defaultValue"];
+    },
+  ): Dict<T>;
+  class List<T extends Generic<unknown>> extends Generic<T["defaultValue"][]> {
+    schema: T;
+    defaultValue: T["defaultValue"][];
+    constructor(schema: T, defaultValue?: T["defaultValue"][]);
+  }
+  function list<T extends Generic<unknown>>(
+    schema: T,
+    defaultValue?: T["defaultValue"][],
+  ): List<T>;
+  /**
+   * Nullable
+   */
+  class Nullable<T extends Generic<unknown>> extends Generic<
+    T["defaultValue"] | null
+  > {
+    schema: T;
+    defaultValue: T["defaultValue"] | null;
+    constructor(schema: T, defaultValue: T["defaultValue"] | null);
+  }
+  function nullable<T extends Generic<unknown>>(
+    schema: T,
+    defaultValue?: T["defaultValue"] | null,
+  ): Nullable<T>;
+  class StringEnum<T extends readonly string[]> extends Generic<string> {
+    readonly options: T;
+    defaultValue: T[number];
+    constructor(options: T, defaultValue: T[number]);
+  }
+  function stringEnum<T extends readonly string[]>(
+    options: T,
+    defaultValue: T[number],
+  ): StringEnum<T>;
+  class StringConst<T extends string> extends Generic<string> {
+    readonly defaultValue: T;
+    constructor(defaultValue: T);
+  }
+  function stringConst<T extends string>(defaultValue: T): StringConst<T>;
+  class AnyOf<T extends readonly Generic<unknown>[]> extends Generic<
+    T[number]["defaultValue"]
+  > {
+    readonly schemas: T;
+    defaultValue: T[number]["defaultValue"];
+    constructor(schemas: T, defaultValue: T[number]["defaultValue"]);
+  }
+  function anyOf<T extends readonly Generic<unknown>[]>(
+    schemas: T,
+    defaultValue: T[number]["defaultValue"],
+  ): AnyOf<T>;
+  class Optional<T extends Generic<unknown>> extends Generic<
+    T["defaultValue"] | undefined
+  > {
+    schema: T;
+    defaultValue: T["defaultValue"] | undefined;
+    constructor(schema: T, defaultValue?: T["defaultValue"] | undefined);
+  }
+  function optional<T extends Generic<unknown>>(
+    schema: T,
+    defaultValue?: T["defaultValue"] | undefined,
+  ): Optional<T>;
+}

package/dist/kokimoki-schema.js

@@ -0,0 +1,162 @@
+export var KokimokiSchema;
+(function (KokimokiSchema) {
+  class Generic {}
+  KokimokiSchema.Generic = Generic;
+  class Number extends Generic {
+    defaultValue;
+    constructor(defaultValue = 0) {
+      super();
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.Number = Number;
+  function number(defaultValue = 0) {
+    return new Number(defaultValue);
+  }
+  KokimokiSchema.number = number;
+  class String extends Generic {
+    defaultValue;
+    constructor(defaultValue = "") {
+      super();
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.String = String;
+  function string(defaultValue = "") {
+    return new String(defaultValue);
+  }
+  KokimokiSchema.string = string;
+  class Boolean extends Generic {
+    defaultValue;
+    constructor(defaultValue = false) {
+      super();
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.Boolean = Boolean;
+  function boolean(defaultValue = false) {
+    return new Boolean(defaultValue);
+  }
+  KokimokiSchema.boolean = boolean;
+  class Struct extends Generic {
+    fields;
+    constructor(fields) {
+      super();
+      this.fields = fields;
+    }
+    get defaultValue() {
+      return Object.entries(this.fields).reduce((acc, [key, field]) => {
+        acc[key] = field.defaultValue;
+        return acc;
+      }, {});
+    }
+    set defaultValue(value) {
+      for (const [key, field] of Object.entries(this.fields)) {
+        field.defaultValue = value[key];
+      }
+    }
+  }
+  KokimokiSchema.Struct = Struct;
+  function struct(schema) {
+    return new Struct(schema);
+  }
+  KokimokiSchema.struct = struct;
+  class Dict {
+    schema;
+    defaultValue;
+    constructor(schema, defaultValue = {}) {
+      this.schema = schema;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.Dict = Dict;
+  function dict(schema, defaultValue = {}) {
+    return new Dict(schema, defaultValue);
+  }
+  KokimokiSchema.dict = dict;
+  class List extends Generic {
+    schema;
+    defaultValue;
+    constructor(schema, defaultValue = []) {
+      super();
+      this.schema = schema;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.List = List;
+  function list(schema, defaultValue = []) {
+    return new List(schema, defaultValue);
+  }
+  KokimokiSchema.list = list;
+  /**
+   * Nullable
+   */
+  class Nullable extends Generic {
+    schema;
+    defaultValue;
+    constructor(schema, defaultValue) {
+      super();
+      this.schema = schema;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.Nullable = Nullable;
+  function nullable(schema, defaultValue = null) {
+    return new Nullable(schema, defaultValue);
+  }
+  KokimokiSchema.nullable = nullable;
+  class StringEnum extends Generic {
+    options;
+    defaultValue;
+    constructor(options, defaultValue) {
+      super();
+      this.options = options;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.StringEnum = StringEnum;
+  function stringEnum(options, defaultValue) {
+    return new StringEnum(options, defaultValue);
+  }
+  KokimokiSchema.stringEnum = stringEnum;
+  class StringConst extends Generic {
+    defaultValue;
+    constructor(defaultValue) {
+      super();
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.StringConst = StringConst;
+  function stringConst(defaultValue) {
+    return new StringConst(defaultValue);
+  }
+  KokimokiSchema.stringConst = stringConst;
+  class AnyOf extends Generic {
+    schemas;
+    defaultValue;
+    constructor(schemas, defaultValue) {
+      super();
+      this.schemas = schemas;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.AnyOf = AnyOf;
+  function anyOf(schemas, defaultValue) {
+    return new AnyOf(schemas, defaultValue);
+  }
+  KokimokiSchema.anyOf = anyOf;
+  class Optional extends Generic {
+    schema;
+    defaultValue;
+    constructor(schema, defaultValue = undefined) {
+      super();
+      this.schema = schema;
+      this.defaultValue = defaultValue;
+    }
+  }
+  KokimokiSchema.Optional = Optional;
+  function optional(schema, defaultValue = undefined) {
+    return new Optional(schema, defaultValue);
+  }
+  KokimokiSchema.optional = optional;
+})(KokimokiSchema || (KokimokiSchema = {}));