@openleaderboard/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 OpenLeaderboard contributors
+
+   Full license text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,80 @@
+# OpenLeaderboard — TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@openleaderboard/sdk.svg?color=c6f135&label=npm)](https://www.npmjs.com/package/@openleaderboard/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@openleaderboard/sdk.svg)](https://www.npmjs.com/package/@openleaderboard/sdk)
+[![license](https://img.shields.io/npm/l/@openleaderboard/sdk.svg)](../../LICENSE)
+
+A dependency-free client for the [OpenLeaderboard](../../README.md) API. Works in
+**browsers** and **Node 18+** (uses the global Fetch API and Web Crypto).
+
+## Install
+
+```bash
+npm install @openleaderboard/sdk
+```
+
+## Quickstart
+
+```ts
+import { LeaderboardClient, NotFoundError } from "@openleaderboard/sdk";
+
+const lb = new LeaderboardClient("https://lb.example.com", "lb_your_api_key");
+
+// Submit (write-behind: durably logged, ranked shortly after).
+await lb.submitScore("high", playerId, 1500);
+
+// Read back.
+const me = await lb.getRank("high", playerId);            // throws NotFoundError if absent
+const top = await lb.getTop("high", 10);
+const near = await lb.getNeighbors("high", playerId, 5);  // me ± 5
+const friends = await lb.getFriends("high", ["alice", "bob"]);
+
+// Segmented / windowed reads (window: literal id or "daily"/"weekly"/"monthly").
+await lb.getTop("high", 10, { segment: "region=eu", window: "daily" });
+```
+
+Errors: `NotFoundError` (404) and `LeaderboardError` (other non-2xx, with `.status`).
+
+### One-time board setup
+
+```ts
+await lb.createBoard("laptimes", { sortOrder: "asc", updatePolicy: "best" });
+await lb.createBoard("weekly", { windows: [{ kind: "all" }, { kind: "weekly" }] });
+```
+
+## Node < 18
+
+Pass a fetch implementation:
+
+```ts
+import fetch from "node-fetch";
+new LeaderboardClient(url, key, { fetch });
+```
+
+## Signed submissions (server-side only)
+
+`signSubmission` and the client's `signingSecret` option produce HMAC signatures
+matching the server's `SIGNING_SECRET`. **Never put the secret in browser/client
+code** — anyone can read it. Sign from a trusted backend instead. Integer scores
+sign identically to the Go server (cross-validated against the server and
+`openssl`).
+
+```ts
+const lb = new LeaderboardClient(url, key, { appId, signingSecret }); // backend only
+```
+
+## Develop
+
+```bash
+npm run typecheck
+npm run build
+npm run test:hmac        # offline HMAC cross-check
+npm run test:e2e         # against a running server (LB_API_KEY env)
+```
+
+## Releasing
+
+`package.json` is authoritative. Bump `version` in your PR; when it merges to
+`main`, CI (`.github/workflows/release-sdk.yml`) publishes exactly that version
+to npm. Changes that don't bump the version are a no-op (already published →
+skipped). npm versions are immutable, so each release needs a new version.

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * OpenLeaderboard TypeScript SDK.
+ *
+ * Dependency-free client over the Fetch API — runs in browsers and Node 18+.
+ *
+ * ```ts
+ * import { LeaderboardClient } from "@openleaderboard/sdk";
+ * const lb = new LeaderboardClient("https://lb.example.com", "lb_your_api_key");
+ * await lb.submitScore("high", playerId, 1500);
+ * const me = await lb.getRank("high", playerId);
+ * const top = await lb.getTop("high", 10);
+ * ```
+ */
+export interface RankEntry {
+    member: string;
+    score: number;
+    rank: number;
+    exact: boolean;
+}
+export interface SubmitResult {
+    accepted: boolean;
+    duplicate: boolean;
+}
+/** Selects the physical board (segment/window) to read. */
+export interface QueryOpts {
+    segment?: string;
+    /** Literal window id ("d=2026-06-13") or cadence keyword ("daily"/"weekly"/"monthly"). */
+    window?: string;
+}
+export interface SubmitOpts {
+    segments?: string[];
+    idem?: string;
+}
+export interface WindowDef {
+    kind: string;
+    customId?: string;
+}
+export interface BoardDef {
+    sortOrder?: "desc" | "asc";
+    updatePolicy?: "best" | "last" | "increment";
+    tieBreak?: "lexical" | "firstToReach";
+    windows?: WindowDef[];
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface ClientOptions {
+    /** App id; required only when signingSecret is set. */
+    appId?: string;
+    /**
+     * Optional HMAC secret for signed submissions. Only use in a TRUSTED backend
+     * — never ship it in browser/client code.
+     */
+    signingSecret?: string;
+    /** Override the fetch implementation (e.g. for Node <18 or tests). */
+    fetch?: FetchLike;
+}
+/** Thrown for non-2xx responses. */
+export declare class LeaderboardError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Thrown when a member or board does not exist (HTTP 404). */
+export declare class NotFoundError extends LeaderboardError {
+    constructor(message: string);
+}
+export declare class LeaderboardClient {
+    private readonly apiKey;
+    private readonly opts;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(baseUrl: string, apiKey: string, opts?: ClientOptions);
+    /** Define a board. Typically a one-time setup call. */
+    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. */
+    getRank(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). */
+    getPage(board: string, offset: number, limit: number, q?: QueryOpts): Promise<RankEntry[]>;
+    /** The member plus up to k entries on each side of it. */
+    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[]>;
+    private send;
+}
+/**
+ * Produces an HMAC-SHA256 submission signature matching the server (pkg/trust).
+ * Exported for trusted server-side signing and testing. Matches Go's float
+ * formatting for the common integer-score case. (Very large/small fractional
+ * scores may format with an exponent in JS and would not match — sign integer
+ * scores, or sign server-side.)
+ */
+export declare function signSubmission(secret: string, app: string, board: string, member: string, score: number, ts: number, nonce: string): Promise<string>;
+export {};

package/dist/index.js

@@ -0,0 +1,138 @@
+/**
+ * OpenLeaderboard TypeScript SDK.
+ *
+ * Dependency-free client over the Fetch API — runs in browsers and Node 18+.
+ *
+ * ```ts
+ * import { LeaderboardClient } from "@openleaderboard/sdk";
+ * const lb = new LeaderboardClient("https://lb.example.com", "lb_your_api_key");
+ * await lb.submitScore("high", playerId, 1500);
+ * const me = await lb.getRank("high", playerId);
+ * const top = await lb.getTop("high", 10);
+ * ```
+ */
+/** Thrown for non-2xx responses. */
+export class LeaderboardError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "LeaderboardError";
+    }
+}
+/** Thrown when a member or board does not exist (HTTP 404). */
+export class NotFoundError extends LeaderboardError {
+    constructor(message) {
+        super(404, message);
+        this.name = "NotFoundError";
+    }
+}
+export class LeaderboardClient {
+    constructor(baseUrl, apiKey, opts = {}) {
+        this.apiKey = apiKey;
+        this.opts = opts;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error("global fetch unavailable; pass opts.fetch (Node <18)");
+        }
+        this.fetchFn = f;
+    }
+    /** Define a board. Typically a one-time setup call. */
+    async createBoard(board, def = {}) {
+        await this.send("POST", "/v1/boards", {
+            board,
+            sort_order: def.sortOrder,
+            update_policy: def.updatePolicy,
+            tie_break: def.tieBreak,
+            windows: def.windows?.map((w) => ({ kind: w.kind, custom_id: w.customId })),
+        });
+    }
+    /** Submit a score (write-behind: durably logged, ranked shortly after). */
+    async submitScore(board, member, score, opts = {}) {
+        const body = {
+            member,
+            score,
+            segments: opts.segments,
+            idem: opts.idem,
+        };
+        if (this.opts.signingSecret) {
+            const ts = Math.floor(Date.now() / 1000);
+            const nonce = randomNonce();
+            body.ts = ts;
+            body.nonce = nonce;
+            body.sig = await signSubmission(this.opts.signingSecret, this.opts.appId ?? "", board, member, score, ts, nonce);
+        }
+        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. */
+    async getRank(board, member, q = {}) {
+        return this.send("GET", `/v1/boards/${enc(board)}/rank${qs({ member, ...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 })}`);
+        return r.entries ?? [];
+    }
+    /** A page of the ranking starting at offset (0-based). */
+    async getPage(board, offset, limit, q = {}) {
+        const r = await this.send("GET", `/v1/boards/${enc(board)}/page${qs({ offset: String(offset), limit: String(limit), ...q })}`);
+        return r.entries ?? [];
+    }
+    /** The member plus up to k entries on each side of it. */
+    async getNeighbors(board, member, k, q = {}) {
+        const r = await this.send("GET", `/v1/boards/${enc(board)}/neighbors${qs({ member, k: String(k), ...q })}`);
+        return r.entries ?? [];
+    }
+    /** Rank an explicit set of members against each other (a friend leaderboard). */
+    async getFriends(board, members, q = {}) {
+        const r = await this.send("POST", `/v1/boards/${enc(board)}/friends${qs({ ...q })}`, { members });
+        return r.entries ?? [];
+    }
+    async send(method, path, body) {
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        let bodyStr;
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyStr = JSON.stringify(body);
+        }
+        const resp = await this.fetchFn(this.baseUrl + path, { method, headers, body: bodyStr });
+        const text = await resp.text();
+        if (resp.status === 404)
+            throw new NotFoundError(text);
+        if (!resp.ok)
+            throw new LeaderboardError(resp.status, `${method} ${path} -> ${resp.status}: ${text}`);
+        return text ? JSON.parse(text) : {};
+    }
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+function qs(params) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v != null && v !== "")
+            p.set(k, v);
+    }
+    const s = p.toString();
+    return s ? `?${s}` : "";
+}
+function randomNonce() {
+    const a = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(a);
+    return [...a].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Produces an HMAC-SHA256 submission signature matching the server (pkg/trust).
+ * Exported for trusted server-side signing and testing. Matches Go's float
+ * formatting for the common integer-score case. (Very large/small fractional
+ * scores may format with an exponent in JS and would not match — sign integer
+ * scores, or sign server-side.)
+ */
+export async function signSubmission(secret, app, board, member, score, ts, nonce) {
+    const canonical = [app, board, member, String(score), String(ts), nonce].join("\n");
+    const encb = new TextEncoder();
+    const key = await globalThis.crypto.subtle.importKey("raw", encb.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await globalThis.crypto.subtle.sign("HMAC", key, encb.encode(canonical));
+    return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@openleaderboard/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript client for the OpenLeaderboard API (browser + Node 18+).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:e2e": "node test/e2e.mjs",
+    "test:hmac": "node test/hmac.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["leaderboard", "gaming", "ranking", "api"],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kodeni-am/leaderboard.git",
+    "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" }
+}