@openleaderboard/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -16,6 +16,14 @@ export interface RankEntry {
     score: number;
     rank: number;
     exact: boolean;
+    nickname?: string;
+}
+/** A registered player: server-minted id + nickname unique per app (case-insensitive). */
+export interface User {
+    user_id: string;
+    nickname: string;
+    created_at?: string;
+    updated_at?: string;
 }
 export interface SubmitResult {
     accepted: boolean;
@@ -30,6 +38,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;
@@ -71,6 +86,10 @@ export declare class LeaderboardError extends Error {
 export declare class NotFoundError extends LeaderboardError {
     constructor(message: string);
 }
+/** Thrown when a nickname is already claimed in this app (HTTP 409). */
+export declare class NicknameTakenError extends LeaderboardError {
+    constructor(message: string);
+}
 export declare class LeaderboardClient {
     private readonly apiKey;
     private readonly opts;
@@ -98,6 +117,23 @@ export declare class LeaderboardClient {
     getNeighbors(board: string, member: string, k: number, q?: QueryOpts): Promise<RankEntry[]>;
     /** Rank an explicit set of members against each other (a friend leaderboard). */
     getFriends(board: string, members: string[], q?: QueryOpts): Promise<RankEntry[]>;
+    /**
+     * Register a player: mints a `plr_...` user id and claims a nickname
+     * (unique per app, case-insensitive). Submit scores with `user_id` as the
+     * member; reads then include the nickname. Throws {@link NicknameTakenError}
+     * if the name is claimed.
+     */
+    registerUser(nickname: string): Promise<User>;
+    /** Fetch a registered player by id. Throws {@link NotFoundError} if absent. */
+    getUser(userId: string): Promise<User>;
+    /** Resolve a nickname (case-insensitive) to its player. */
+    getUserByNickname(nickname: string): Promise<User>;
+    /**
+     * Change a player's nickname. The user id — and therefore board data and
+     * HMAC signatures — is unaffected. Throws {@link NicknameTakenError} on
+     * conflict.
+     */
+    renameUser(userId: string, nickname: string): Promise<User>;
     private send;
 }
 /**

package/dist/index.js

@@ -26,6 +26,13 @@ export class NotFoundError extends LeaderboardError {
         this.name = "NotFoundError";
     }
 }
+/** Thrown when a nickname is already claimed in this app (HTTP 409). */
+export class NicknameTakenError extends LeaderboardError {
+    constructor(message) {
+        super(409, message);
+        this.name = "NicknameTakenError";
+    }
+}
 export class LeaderboardClient {
     constructor(baseUrl, apiKey, opts = {}) {
         this.apiKey = apiKey;
@@ -58,6 +65,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);
@@ -102,6 +110,31 @@ export class LeaderboardClient {
         const r = await this.send("POST", `/v1/boards/${enc(board)}/friends${qs({ ...q })}`, { members });
         return r.entries ?? [];
     }
+    /**
+     * Register a player: mints a `plr_...` user id and claims a nickname
+     * (unique per app, case-insensitive). Submit scores with `user_id` as the
+     * member; reads then include the nickname. Throws {@link NicknameTakenError}
+     * if the name is claimed.
+     */
+    async registerUser(nickname) {
+        return this.send("POST", "/v1/users", { nickname });
+    }
+    /** Fetch a registered player by id. Throws {@link NotFoundError} if absent. */
+    async getUser(userId) {
+        return this.send("GET", `/v1/users/${enc(userId)}`);
+    }
+    /** Resolve a nickname (case-insensitive) to its player. */
+    async getUserByNickname(nickname) {
+        return this.send("GET", `/v1/users${qs({ nickname })}`);
+    }
+    /**
+     * Change a player's nickname. The user id — and therefore board data and
+     * HMAC signatures — is unaffected. Throws {@link NicknameTakenError} on
+     * conflict.
+     */
+    async renameUser(userId, nickname) {
+        return this.send("PATCH", `/v1/users/${enc(userId)}`, { nickname });
+    }
     async send(method, path, body) {
         const headers = { Authorization: `Bearer ${this.apiKey}` };
         let bodyStr;
@@ -113,6 +146,8 @@ export class LeaderboardClient {
         const text = await resp.text();
         if (resp.status === 404)
             throw new NotFoundError(text);
+        if (resp.status === 409)
+            throw new NicknameTakenError(text);
         if (!resp.ok)
             throw new LeaderboardError(resp.status, `${method} ${path} -> ${resp.status}: ${text}`);
         return text ? JSON.parse(text) : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openleaderboard/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TypeScript client for the OpenLeaderboard API (browser + Node 18+).",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,9 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -20,7 +22,12 @@
     "test:hmac": "node test/hmac.mjs",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["leaderboard", "gaming", "ranking", "api"],
+  "keywords": [
+    "leaderboard",
+    "gaming",
+    "ranking",
+    "api"
+  ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,8 +35,16 @@
     "directory": "sdk/typescript"
   },
   "homepage": "https://github.com/kodeni-am/leaderboard/tree/main/sdk/typescript#readme",
-  "bugs": { "url": "https://github.com/kodeni-am/leaderboard/issues" },
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=18" },
-  "devDependencies": { "typescript": "^5.5.0" }
+  "bugs": {
+    "url": "https://github.com/kodeni-am/leaderboard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
 }