@openleaderboard/sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -30,6 +30,13 @@ export interface QueryOpts {
 export interface SubmitOpts {
     segments?: string[];
     idem?: string;
+    /**
+     * Event time of the score. Determines which time-window bucket it lands in
+     * (e.g. the daily board) — set it to the session start so a run that crosses
+     * midnight counts for the day it began, rather than when it was submitted.
+     * Accepts a Date or an ISO-8601 string; defaults to server receive time.
+     */
+    time?: Date | string;
 }
 export interface WindowDef {
     kind: string;
@@ -40,6 +47,15 @@ export interface BoardDef {
     updatePolicy?: "best" | "last" | "increment";
     tieBreak?: "lexical" | "firstToReach";
     windows?: WindowDef[];
+    /**
+     * Enable the approximate-rank tier (a score histogram) so {@link
+     * LeaderboardClient.getApproxRank} can estimate rank in O(buckets) on very
+     * large boards. Requires `approxMax > approxMin`; `approxBuckets` defaults to 1024.
+     */
+    approxRank?: boolean;
+    approxMin?: number;
+    approxMax?: number;
+    approxBuckets?: number;
 }
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface ClientOptions {
@@ -72,8 +88,15 @@ export declare class LeaderboardClient {
     createBoard(board: string, def?: BoardDef): Promise<void>;
     /** Submit a score (write-behind: durably logged, ranked shortly after). */
     submitScore(board: string, member: string, score: number, opts?: SubmitOpts): Promise<SubmitResult>;
-    /** A member's rank. Throws {@link NotFoundError} if absent. */
+    /** A member's exact rank (O(log N)). Throws {@link NotFoundError} if absent. */
     getRank(board: string, member: string, q?: QueryOpts): Promise<RankEntry>;
+    /**
+     * A member's approximate rank from the board's score histogram (O(buckets),
+     * `exact: false`). The board must be created with `approxRank: true`; on very
+     * large boards this avoids the cost of an exact rank scan. Throws
+     * {@link NotFoundError} if the member is absent.
+     */
+    getApproxRank(board: string, member: string, q?: QueryOpts): Promise<RankEntry>;
     /** Top N entries (rank 1..N). */
     getTop(board: string, n: number, q?: QueryOpts): Promise<RankEntry[]>;
     /** A page of the ranking starting at offset (0-based). */

package/dist/index.js

@@ -45,6 +45,10 @@ export class LeaderboardClient {
             update_policy: def.updatePolicy,
             tie_break: def.tieBreak,
             windows: def.windows?.map((w) => ({ kind: w.kind, custom_id: w.customId })),
+            approx_rank: def.approxRank,
+            approx_min: def.approxMin,
+            approx_max: def.approxMax,
+            approx_buckets: def.approxBuckets,
         });
     }
     /** Submit a score (write-behind: durably logged, ranked shortly after). */
@@ -54,6 +58,7 @@ export class LeaderboardClient {
             score,
             segments: opts.segments,
             idem: opts.idem,
+            time: opts.time instanceof Date ? opts.time.toISOString() : opts.time,
         };
         if (this.opts.signingSecret) {
             const ts = Math.floor(Date.now() / 1000);
@@ -65,10 +70,19 @@ export class LeaderboardClient {
         const r = await this.send("POST", `/v1/boards/${enc(board)}/scores`, body);
         return { accepted: !!r.accepted, duplicate: !!r.duplicate };
     }
-    /** A member's rank. Throws {@link NotFoundError} if absent. */
+    /** A member's exact rank (O(log N)). Throws {@link NotFoundError} if absent. */
     async getRank(board, member, q = {}) {
         return this.send("GET", `/v1/boards/${enc(board)}/rank${qs({ member, ...q })}`);
     }
+    /**
+     * A member's approximate rank from the board's score histogram (O(buckets),
+     * `exact: false`). The board must be created with `approxRank: true`; on very
+     * large boards this avoids the cost of an exact rank scan. Throws
+     * {@link NotFoundError} if the member is absent.
+     */
+    async getApproxRank(board, member, q = {}) {
+        return this.send("GET", `/v1/boards/${enc(board)}/rank${qs({ member, approx: "true", ...q })}`);
+    }
     /** Top N entries (rank 1..N). */
     async getTop(board, n, q = {}) {
         const r = await this.send("GET", `/v1/boards/${enc(board)}/top${qs({ n: String(n), ...q })}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openleaderboard/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript client for the OpenLeaderboard API (browser + Node 18+).",
   "type": "module",
   "main": "./dist/index.js",