@flare-engine/leaderboards 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Otto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @flare-engine/leaderboards
+
+Typed `LeaderboardsProvider` interface + `NoopLeaderboardsProvider` + React context. Stub-only at 0.1.0; concrete adapters (Game Center, Google Play Games, Steam) land at 0.2.0.
+
+## Install
+
+```sh
+bun add @flare-engine/leaderboards
+```
+
+## Usage
+
+```tsx
+import {
+  LeaderboardsContext,
+  useLeaderboards,
+  NoopLeaderboardsProvider,
+} from '@flare-engine/leaderboards';
+
+export function App() {
+  return (
+    <LeaderboardsContext.Provider value={NoopLeaderboardsProvider}>
+      {/* ... */}
+    </LeaderboardsContext.Provider>
+  );
+}
+```
+
+`useLeaderboards()` returns the provider; call `submit(boardId, score)`, `fetch(boardId)`, etc. against the interface — swapping `NoopLeaderboardsProvider` for a real adapter at 0.2.0 requires no consumer changes.
+
+## Recipe — env-var-gated lazy load
+
+When 0.2.0 adapters land (e.g. `@flare-engine/leaderboards-gamecenter`), wrap them behind an env-var gate so CI / unit tests / dev builds without API keys fall back to `NoopLeaderboardsProvider` and never touch the native SDK. See [.github/skills/flare-tier2-stubs/SKILL.md § Lazy-SDK adapter recipe](../../.github/skills/flare-tier2-stubs/SKILL.md#lazy-sdk-adapter-recipe) for the full pattern; canonical implementation at [apps/pan-tvardowski/src/iap/provider.ts](../../apps/pan-tvardowski/src/iap/provider.ts) (RevenueCat / IAP — same shape).

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import * as react from 'react';
+
+/** Opaque leaderboard identifier — adapter-defined (e.g., "daily_high_score"). */
+type LeaderboardId = string;
+/** A single leaderboard row. */
+interface ScoreEntry {
+    playerId: string;
+    displayName: string;
+    score: number;
+    rank: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Leaderboard provider interface. Consumers supply a concrete adapter (Game
+ * Center, Google Play Games, Steam, custom backend) at the app boundary.
+ * 0.1.0 ships the interface + a no-op default so downstream packages can
+ * depend on it without forcing a platform choice.
+ */
+interface LeaderboardsProvider {
+    submitScore(id: LeaderboardId, score: number, meta?: Record<string, unknown>): Promise<void>;
+    getTopN(id: LeaderboardId, n: number): Promise<readonly ScoreEntry[]>;
+    getPlayerRank(id: LeaderboardId): Promise<number | null>;
+}
+/**
+ * Default no-op provider. Submissions resolve silently; queries return empty
+ * arrays and `null` rank.
+ */
+declare const NoopLeaderboardsProvider: LeaderboardsProvider;
+
+/**
+ * React context carrying the active `LeaderboardsProvider`. Defaults to
+ * `NoopLeaderboardsProvider` so `useLeaderboards()` never throws on a bare
+ * tree — consumers wrap their app in a `<LeaderboardsContext.Provider>` with
+ * a real adapter when they need one.
+ */
+declare const LeaderboardsContext: react.Context<LeaderboardsProvider>;
+/** Hook returning the current `LeaderboardsProvider`. */
+declare function useLeaderboards(): LeaderboardsProvider;
+
+export { type LeaderboardId, LeaderboardsContext, type LeaderboardsProvider, NoopLeaderboardsProvider, type ScoreEntry, useLeaderboards };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import * as react from 'react';
+
+/** Opaque leaderboard identifier — adapter-defined (e.g., "daily_high_score"). */
+type LeaderboardId = string;
+/** A single leaderboard row. */
+interface ScoreEntry {
+    playerId: string;
+    displayName: string;
+    score: number;
+    rank: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Leaderboard provider interface. Consumers supply a concrete adapter (Game
+ * Center, Google Play Games, Steam, custom backend) at the app boundary.
+ * 0.1.0 ships the interface + a no-op default so downstream packages can
+ * depend on it without forcing a platform choice.
+ */
+interface LeaderboardsProvider {
+    submitScore(id: LeaderboardId, score: number, meta?: Record<string, unknown>): Promise<void>;
+    getTopN(id: LeaderboardId, n: number): Promise<readonly ScoreEntry[]>;
+    getPlayerRank(id: LeaderboardId): Promise<number | null>;
+}
+/**
+ * Default no-op provider. Submissions resolve silently; queries return empty
+ * arrays and `null` rank.
+ */
+declare const NoopLeaderboardsProvider: LeaderboardsProvider;
+
+/**
+ * React context carrying the active `LeaderboardsProvider`. Defaults to
+ * `NoopLeaderboardsProvider` so `useLeaderboards()` never throws on a bare
+ * tree — consumers wrap their app in a `<LeaderboardsContext.Provider>` with
+ * a real adapter when they need one.
+ */
+declare const LeaderboardsContext: react.Context<LeaderboardsProvider>;
+/** Hook returning the current `LeaderboardsProvider`. */
+declare function useLeaderboards(): LeaderboardsProvider;
+
+export { type LeaderboardId, LeaderboardsContext, type LeaderboardsProvider, NoopLeaderboardsProvider, type ScoreEntry, useLeaderboards };

package/dist/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LeaderboardsContext: () => LeaderboardsContext,
+  NoopLeaderboardsProvider: () => NoopLeaderboardsProvider,
+  useLeaderboards: () => useLeaderboards
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.ts
+var NoopLeaderboardsProvider = {
+  async submitScore() {
+  },
+  async getTopN() {
+    return [];
+  },
+  async getPlayerRank() {
+    return null;
+  }
+};
+
+// src/context.ts
+var import_react = require("react");
+var LeaderboardsContext = (0, import_react.createContext)(NoopLeaderboardsProvider);
+function useLeaderboards() {
+  return (0, import_react.useContext)(LeaderboardsContext);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LeaderboardsContext,
+  NoopLeaderboardsProvider,
+  useLeaderboards
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/provider.ts","../src/context.ts"],"sourcesContent":["export {\n  NoopLeaderboardsProvider,\n  type LeaderboardId,\n  type LeaderboardsProvider,\n  type ScoreEntry,\n} from './provider.js';\nexport { LeaderboardsContext, useLeaderboards } from './context.js';\n","/** Opaque leaderboard identifier — adapter-defined (e.g., \"daily_high_score\"). */\nexport type LeaderboardId = string;\n\n/** A single leaderboard row. */\nexport interface ScoreEntry {\n  playerId: string;\n  displayName: string;\n  score: number;\n  rank: number;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Leaderboard provider interface. Consumers supply a concrete adapter (Game\n * Center, Google Play Games, Steam, custom backend) at the app boundary.\n * 0.1.0 ships the interface + a no-op default so downstream packages can\n * depend on it without forcing a platform choice.\n */\nexport interface LeaderboardsProvider {\n  submitScore(id: LeaderboardId, score: number, meta?: Record<string, unknown>): Promise<void>;\n  getTopN(id: LeaderboardId, n: number): Promise<readonly ScoreEntry[]>;\n  getPlayerRank(id: LeaderboardId): Promise<number | null>;\n}\n\n/**\n * Default no-op provider. Submissions resolve silently; queries return empty\n * arrays and `null` rank.\n */\nexport const NoopLeaderboardsProvider: LeaderboardsProvider = {\n  async submitScore(): Promise<void> {\n    // no-op\n  },\n  async getTopN(): Promise<readonly ScoreEntry[]> {\n    return [];\n  },\n  async getPlayerRank(): Promise<number | null> {\n    return null;\n  },\n};\n","import { createContext, useContext } from 'react';\nimport { type LeaderboardsProvider, NoopLeaderboardsProvider } from './provider.js';\n\n/**\n * React context carrying the active `LeaderboardsProvider`. Defaults to\n * `NoopLeaderboardsProvider` so `useLeaderboards()` never throws on a bare\n * tree — consumers wrap their app in a `<LeaderboardsContext.Provider>` with\n * a real adapter when they need one.\n */\nexport const LeaderboardsContext = createContext<LeaderboardsProvider>(NoopLeaderboardsProvider);\n\n/** Hook returning the current `LeaderboardsProvider`. */\nexport function useLeaderboards(): LeaderboardsProvider {\n  return useContext(LeaderboardsContext);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC4BO,IAAM,2BAAiD;AAAA,EAC5D,MAAM,cAA6B;AAAA,EAEnC;AAAA,EACA,MAAM,UAA0C;AAC9C,WAAO,CAAC;AAAA,EACV;AAAA,EACA,MAAM,gBAAwC;AAC5C,WAAO;AAAA,EACT;AACF;;;ACtCA,mBAA0C;AASnC,IAAM,0BAAsB,4BAAoC,wBAAwB;AAGxF,SAAS,kBAAwC;AACtD,aAAO,yBAAW,mBAAmB;AACvC;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,24 @@
+// src/provider.ts
+var NoopLeaderboardsProvider = {
+  async submitScore() {
+  },
+  async getTopN() {
+    return [];
+  },
+  async getPlayerRank() {
+    return null;
+  }
+};
+
+// src/context.ts
+import { createContext, useContext } from "react";
+var LeaderboardsContext = createContext(NoopLeaderboardsProvider);
+function useLeaderboards() {
+  return useContext(LeaderboardsContext);
+}
+export {
+  LeaderboardsContext,
+  NoopLeaderboardsProvider,
+  useLeaderboards
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider.ts","../src/context.ts"],"sourcesContent":["/** Opaque leaderboard identifier — adapter-defined (e.g., \"daily_high_score\"). */\nexport type LeaderboardId = string;\n\n/** A single leaderboard row. */\nexport interface ScoreEntry {\n  playerId: string;\n  displayName: string;\n  score: number;\n  rank: number;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Leaderboard provider interface. Consumers supply a concrete adapter (Game\n * Center, Google Play Games, Steam, custom backend) at the app boundary.\n * 0.1.0 ships the interface + a no-op default so downstream packages can\n * depend on it without forcing a platform choice.\n */\nexport interface LeaderboardsProvider {\n  submitScore(id: LeaderboardId, score: number, meta?: Record<string, unknown>): Promise<void>;\n  getTopN(id: LeaderboardId, n: number): Promise<readonly ScoreEntry[]>;\n  getPlayerRank(id: LeaderboardId): Promise<number | null>;\n}\n\n/**\n * Default no-op provider. Submissions resolve silently; queries return empty\n * arrays and `null` rank.\n */\nexport const NoopLeaderboardsProvider: LeaderboardsProvider = {\n  async submitScore(): Promise<void> {\n    // no-op\n  },\n  async getTopN(): Promise<readonly ScoreEntry[]> {\n    return [];\n  },\n  async getPlayerRank(): Promise<number | null> {\n    return null;\n  },\n};\n","import { createContext, useContext } from 'react';\nimport { type LeaderboardsProvider, NoopLeaderboardsProvider } from './provider.js';\n\n/**\n * React context carrying the active `LeaderboardsProvider`. Defaults to\n * `NoopLeaderboardsProvider` so `useLeaderboards()` never throws on a bare\n * tree — consumers wrap their app in a `<LeaderboardsContext.Provider>` with\n * a real adapter when they need one.\n */\nexport const LeaderboardsContext = createContext<LeaderboardsProvider>(NoopLeaderboardsProvider);\n\n/** Hook returning the current `LeaderboardsProvider`. */\nexport function useLeaderboards(): LeaderboardsProvider {\n  return useContext(LeaderboardsContext);\n}\n"],"mappings":";AA4BO,IAAM,2BAAiD;AAAA,EAC5D,MAAM,cAA6B;AAAA,EAEnC;AAAA,EACA,MAAM,UAA0C;AAC9C,WAAO,CAAC;AAAA,EACV;AAAA,EACA,MAAM,gBAAwC;AAC5C,WAAO;AAAA,EACT;AACF;;;ACtCA,SAAS,eAAe,kBAAkB;AASnC,IAAM,sBAAsB,cAAoC,wBAAwB;AAGxF,SAAS,kBAAwC;AACtD,SAAO,WAAW,mBAAmB;AACvC;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@flare-engine/leaderboards",
+  "version": "0.1.0",
+  "description": "Leaderboard provider interface (consumer-supplied adapter)",
+  "keywords": ["flare-engine", "leaderboards", "provider", "interface"],
+  "license": "MIT",
+  "author": "Grzegorz Otto",
+  "homepage": "https://github.com/grzott/flare-engine#readme",
+  "bugs": {
+    "url": "https://github.com/grzott/flare-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzott/flare-engine.git",
+    "directory": "packages/leaderboards"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "lint": "biome check src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false
+}