scorezilla 0.3.1 → 0.4.0

package/API.md

@@ -156,8 +156,9 @@ for (const e of entries) console.log(`${e.rank}. ${e.playerId}: ${e.score}`);
 
 ### `getPlayerRank`
 
-`GET /v1/boards/:boardId/players/:playerId/rank`. Returns 404 (`not_found`) if
-the player has no submission yet.
+`GET /v1/boards/:boardId/players/:playerId/rank`. "No entry yet" is a normal
+result (`{ ranked: false }`), **not** an error — narrow on `ranked` before
+reading `rank`. A `not_found` (404) is thrown only when the board doesn't exist.
 
 ```ts
 interface GetPlayerRankInput {
@@ -165,15 +166,24 @@ interface GetPlayerRankInput {
   playerId: string;
 }
 
-interface PlayerRankResponse {
-  ok: true;
-  boardId: string;
-  playerId: string;
-  rank: number;
-  score: number;
-  submittedAt: number;
-  totalEntries: number;
-}
+type PlayerRankResponse =
+  | {
+      ok: true;
+      boardId: string;
+      playerId: string;
+      ranked: true;
+      rank: number;
+      score: number;
+      submittedAt: number;
+      totalEntries: number;
+    }
+  | { ok: true; boardId: string; playerId: string; ranked: false; rank: null; score: null };
+```
+
+```ts
+const r = await sz.getPlayerRank({ boardId, playerId });
+if (r.ranked) console.log(`Rank ${r.rank} of ${r.totalEntries}`);
+else console.log('No submission yet.');
 ```
 
 ### `getWindowAround`

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- [#57](https://github.com/isco-tec/scorezilla-js/pull/57) [`cba6107`](https://github.com/isco-tec/scorezilla-js/commit/cba61078b2a66bb4c9d0d911dee8dd776e7b69d5) Thanks [@isco-tec](https://github.com/isco-tec)! - `getPlayerRank` no longer treats "no entry yet" as an error.
+
+  The rank endpoint now returns `200 { ranked: false }` for a player with no submission instead of a `404` — a 404 forced an un-suppressable red console line in every integrator's devtools for a perfectly normal "has this player scored?" check. `PlayerRankResponse` is now a union discriminated on `ranked`: narrow on it before reading `rank`/`score`. A `not_found` is still thrown only when the board itself doesn't exist.
+
+  Migration:
+
+  ```ts
+  // Before
+  try {
+    const { rank } = await sz.getPlayerRank({ boardId, playerId });
+  } catch (e) {
+    if (e instanceof ScorezillaError && e.isNotFound()) {
+      /* no entry */
+    }
+  }
+
+  // After
+  const r = await sz.getPlayerRank({ boardId, playerId });
+  if (r.ranked) {
+    /* r.rank, r.score, … */
+  } else {
+    /* no entry yet */
+  }
+  ```
+
 ## 0.3.1
 
 ### Patch Changes

package/dist/{errors-CWTmormh.d.cts → errors-BhPRMQiV.d.cts}

@@ -178,15 +178,36 @@ interface LeaderboardResponse {
     limit: number;
     entries: RankedEntry[];
 }
-/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
-interface PlayerRankResponse {
+/**
+ * Payload from `GET /v1/boards/:boardId/players/:playerId/rank`.
+ *
+ * Discriminated on `ranked`. "No entry yet" is a normal state, not an error:
+ * the API returns `200 { ranked: false }` (not a 404 — a 404 spammed an
+ * un-suppressable red console line for every benign "has this player scored?"
+ * check). A 404 is now reserved for a genuinely missing board.
+ *
+ * @example
+ * ```ts
+ * const r = await sz.getPlayerRank({ boardId, playerId });
+ * if (r.ranked) console.log(`Rank ${r.rank} of ${r.totalEntries}`);
+ * else console.log('No submission yet.');
+ * ```
+ */
+type PlayerRankResponse = {
     boardId: string;
     playerId: string;
+    ranked: true;
     rank: number;
     score: number;
     submittedAt: number;
     totalEntries: number;
-}
+} | {
+    boardId: string;
+    playerId: string;
+    ranked: false;
+    rank: null;
+    score: null;
+};
 /** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
 interface WindowAroundResponse {
     boardId: string;

package/dist/{errors-CWTmormh.d.ts → errors-BhPRMQiV.d.ts}

@@ -178,15 +178,36 @@ interface LeaderboardResponse {
     limit: number;
     entries: RankedEntry[];
 }
-/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
-interface PlayerRankResponse {
+/**
+ * Payload from `GET /v1/boards/:boardId/players/:playerId/rank`.
+ *
+ * Discriminated on `ranked`. "No entry yet" is a normal state, not an error:
+ * the API returns `200 { ranked: false }` (not a 404 — a 404 spammed an
+ * un-suppressable red console line for every benign "has this player scored?"
+ * check). A 404 is now reserved for a genuinely missing board.
+ *
+ * @example
+ * ```ts
+ * const r = await sz.getPlayerRank({ boardId, playerId });
+ * if (r.ranked) console.log(`Rank ${r.rank} of ${r.totalEntries}`);
+ * else console.log('No submission yet.');
+ * ```
+ */
+type PlayerRankResponse = {
     boardId: string;
     playerId: string;
+    ranked: true;
     rank: number;
     score: number;
     submittedAt: number;
     totalEntries: number;
-}
+} | {
+    boardId: string;
+    playerId: string;
+    ranked: false;
+    rank: null;
+    score: null;
+};
 /** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
 interface WindowAroundResponse {
     boardId: string;

package/dist/index.cjs

@@ -656,7 +656,7 @@ function validateMetadata(metadata) {
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.3.1";
+  static version = "0.4.0";
   #config;
   #userAgent;
   #authHeader;
@@ -746,22 +746,19 @@ var Scorezilla = class _Scorezilla {
   /**
    * Fetch a single player's rank on a board.
    *
-   * Maps to `GET /v1/boards/:boardId/players/:playerId/rank`. Returns 404
-   * (`not_found`) if the player has no entry yet.
+   * Maps to `GET /v1/boards/:boardId/players/:playerId/rank`. "No entry yet"
+   * is a normal result, NOT an error: the response is `{ ranked: false }`
+   * (narrow on `ranked` before reading `rank`). A `not_found` is thrown only
+   * when the board itself doesn't exist.
    *
    * @example
    * ```ts
-   * try {
-   *   const { rank, score } = await sz.getPlayerRank({ boardId, playerId: 'alice' });
-   *   console.log(`Alice is rank ${rank} with score ${score}`);
-   * } catch (e) {
-   *   if (e instanceof ScorezillaError && e.isNotFound()) {
-   *     console.log('Alice has no submission on this board yet.');
-   *   } else throw e;
-   * }
+   * const r = await sz.getPlayerRank({ boardId, playerId: 'alice' });
+   * if (r.ranked) console.log(`Alice is rank ${r.rank} with score ${r.score}`);
+   * else console.log('Alice has no submission on this board yet.');
    * ```
    *
-   * @throws {ScorezillaError} `not_found` (player has no submission),
+   * @throws {ScorezillaError} `not_found` (board does not exist),
    *   `network_error`, `timeout`.
    * @since 0.1.0
    * @stability stable
@@ -841,7 +838,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.3.1";
+var SDK_VERSION = "0.4.0";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;