@oasiz/sdk 1.5.2 → 1.5.4

package/README.md

@@ -21,7 +21,9 @@ Typed SDK for integrating browser games with the Oasiz platform: score, haptics,
 npm install @oasiz/sdk
 ```
 
-### Quick start
+The published package includes ESM, CommonJS, and TypeScript declarations.
+
+## Quick start
 
 ```ts
 import { oasiz } from "@oasiz/sdk";
@@ -36,10 +38,10 @@ oasiz.saveGameState({ level, coins: 42 });
 // 3. Trigger haptics on key events
 oasiz.triggerHaptic("medium");
 
-// 4. Respect the host's top safe area
+// 4. Respect the host's top safe area (percent of viewport height → CSS vh)
 document.documentElement.style.setProperty(
   "--safe-top",
-  `${oasiz.safeAreaTop}px`,
+  `${oasiz.safeAreaTop}vh`,
 );
 
 // 5. Submit score when the game ends
@@ -194,15 +196,15 @@ private onGameOver(): void {
 
 ### Layout
 
-Use the runtime safe-area value instead of hardcoded top offsets. The host reports the current top inset in **CSS pixels** for persistent chrome such as the back button and top controls.
+Use the runtime safe-area value instead of hardcoded top offsets. The SDK returns the top inset as **a percentage of the viewport height (0–100)**. If the host exposes CSS pixels via `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`, the SDK converts using `window.innerHeight`. The host may instead set **`window.getSafeAreaTopPercent()`** or **`window.__OASIZ_SAFE_AREA_TOP_PERCENT__`** (0–100) and that value is used directly.
 
 #### `oasiz.getSafeAreaTop(): number`
 
-Returns the current top inset. The host may expose `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`. Unsupported hosts return `0`.
+Returns the top inset as a percentage of viewport height (0–100). To get pixels in JavaScript, use `(getSafeAreaTop() / 100) * window.innerHeight`. In CSS, the same value matches **`vh`** units (for example `12.5vh` for 12.5% of the viewport height). Unsupported hosts return `0`.
 
 ```ts
-const safeTop = oasiz.getSafeAreaTop();
-document.documentElement.style.setProperty("--safe-top", `${safeTop}px`);
+const safeTopPct = oasiz.getSafeAreaTop();
+document.documentElement.style.setProperty("--safe-top", `${safeTopPct}vh`);
 ```
 
 #### `oasiz.safeAreaTop`
@@ -453,9 +455,10 @@ public class GameManager : MonoBehaviour
         OasizSDK.OnPause += OnPause;
         OasizSDK.OnResume += OnResume;
 
-        // Offset UI for the host's top safe area
-        float safeTop = OasizSDK.SafeAreaTop;
-        Debug.Log($"Safe area top: {safeTop}px");
+        // Offset UI for the host's top safe area (0–100 percent of Screen.height)
+        float safeTopPct = OasizSDK.SafeAreaTop;
+        float safeTopPx = safeTopPct / 100f * Screen.height;
+        Debug.Log($"Safe area top: {safeTopPx}px ({safeTopPct}% of height)");
 
         // Emit score normalization anchors
         OasizSDK.EmitScoreConfig(new ScoreConfig(
@@ -498,7 +501,7 @@ public class GameManager : MonoBehaviour
 | `oasiz.loadGameState()` | `OasizSDK.LoadGameState()` → `Dictionary<string, object>` |
 | `oasiz.saveGameState(obj)` | `OasizSDK.SaveGameState(Dictionary<string, object>)` |
 | `oasiz.flushGameState()` | `OasizSDK.FlushGameState()` |
-| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, CSS px) |
+| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, 0–100, % of viewport height) |
 | `oasiz.setLeaderboardVisible(v)` | `OasizSDK.SetLeaderboardVisible(bool)` |
 | `oasiz.onPause` / `onResume` | `OasizSDK.OnPause` / `OnResume` static events |
 | `oasiz.onBackButton` | `OasizSDK.OnBackButton` or `SubscribeBackButton(Action)` (reference-counts `__oasizSetBackOverride`) |

package/dist/index.cjs

@@ -20,10 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  addScore: () => addScore,
   enableLogOverlay: () => enableLogOverlay,
   flushGameState: () => flushGameState,
   getGameId: () => getGameId,
   getPlayerAvatar: () => getPlayerAvatar,
+  getPlayerCharacter: () => getPlayerCharacter,
+  getPlayerId: () => getPlayerId,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   getSafeAreaTop: () => getSafeAreaTop,
@@ -37,6 +40,7 @@ __export(index_exports, {
   openInviteModal: () => openInviteModal,
   saveGameState: () => saveGameState,
   setLeaderboardVisible: () => setLeaderboardVisible,
+  setScore: () => setScore,
   share: () => share,
   shareRoomCode: () => shareRoomCode,
   submitScore: () => submitScore,
@@ -44,7 +48,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/haptics.ts
+// src/character.ts
 function isDevelopment() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -55,13 +59,48 @@ function getBridgeWindow() {
   }
   return window;
 }
-function triggerHaptic(type) {
+function warnMissingBridge(methodName) {
+  if (isDevelopment()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+async function getPlayerCharacter() {
   const bridge = getBridgeWindow();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    warnMissingBridge("getPlayerCharacter");
+    return null;
+  }
+  try {
+    const result = await bridge.__oasizGetPlayerCharacter();
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment()) {
+      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
+    }
+    return null;
+  }
+}
+
+// src/haptics.ts
+function isDevelopment2() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow2() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function triggerHaptic(type) {
+  const bridge = getBridgeWindow2();
   if (typeof bridge?.triggerHaptic === "function") {
     bridge.triggerHaptic(type);
     return;
   }
-  if (isDevelopment()) {
+  if (isDevelopment2()) {
     console.warn(
       "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
     );
@@ -960,70 +999,74 @@ function enableLogOverlay(options = {}) {
 }
 
 // src/multiplayer.ts
-function isDevelopment2() {
+function isDevelopment3() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow2() {
+function getBridgeWindow3() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
 function shareRoomCode(roomCode, options) {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   if (typeof bridge?.shareRoomCode === "function") {
     bridge.shareRoomCode(roomCode, options);
     return;
   }
-  if (isDevelopment2()) {
+  if (isDevelopment3()) {
     console.warn(
       "[oasiz/sdk] shareRoomCode bridge is unavailable. This is expected in local development."
     );
   }
 }
 function openInviteModal() {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   if (typeof bridge?.openInviteModal === "function") {
     bridge.openInviteModal();
     return;
   }
-  if (isDevelopment2()) {
+  if (isDevelopment3()) {
     console.warn(
       "[oasiz/sdk] openInviteModal bridge is unavailable. This is expected in local development."
     );
   }
 }
 function getGameId() {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   return bridge?.__GAME_ID__;
 }
 function getRoomCode() {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   return bridge?.__ROOM_CODE__;
 }
+function getPlayerId() {
+  const bridge = getBridgeWindow3();
+  return bridge?.__PLAYER_ID__;
+}
 function getPlayerName() {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   return bridge?.__PLAYER_NAME__;
 }
 function getPlayerAvatar() {
-  const bridge = getBridgeWindow2();
+  const bridge = getBridgeWindow3();
   return bridge?.__PLAYER_AVATAR__;
 }
 
 // src/score.ts
-function isDevelopment3() {
+function isDevelopment4() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function warnMissingBridge(methodName) {
-  if (isDevelopment3()) {
+function warnMissingBridge2(methodName) {
+  if (isDevelopment4()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
-function getBridgeWindow3() {
+function getBridgeWindow4() {
   if (typeof window === "undefined") {
     return void 0;
   }
@@ -1031,33 +1074,92 @@ function getBridgeWindow3() {
 }
 function submitScore(score) {
   if (!Number.isFinite(score)) {
-    if (isDevelopment3()) {
+    if (isDevelopment4()) {
       console.warn("[oasiz/sdk] submitScore expected a finite number:", score);
     }
     return;
   }
-  const bridge = getBridgeWindow3();
+  const bridge = getBridgeWindow4();
   const normalizedScore = Math.max(0, Math.floor(score));
   if (typeof bridge?.submitScore === "function") {
     bridge.submitScore(normalizedScore);
     return;
   }
-  warnMissingBridge("submitScore");
+  warnMissingBridge2("submitScore");
+}
+
+// src/score-edit.ts
+function isDevelopment5() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow5() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function warnMissingBridge3(methodName) {
+  if (isDevelopment5()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+async function editScore(payload, methodName) {
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizEditScore !== "function") {
+    warnMissingBridge3(methodName);
+    return null;
+  }
+  try {
+    const result = await bridge.__oasizEditScore(payload);
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment5()) {
+      console.error("[oasiz/sdk] " + methodName + " failed:", error);
+    }
+    return null;
+  }
+}
+async function addScore(delta) {
+  if (!Number.isInteger(delta)) {
+    if (isDevelopment5()) {
+      console.warn("[oasiz/sdk] addScore expected an integer:", delta);
+    }
+    return null;
+  }
+  if (delta === 0) {
+    return null;
+  }
+  return editScore({ delta }, "addScore");
+}
+async function setScore(score) {
+  if (!Number.isInteger(score) || score < 0) {
+    if (isDevelopment5()) {
+      console.warn(
+        "[oasiz/sdk] setScore expected a non-negative integer:",
+        score
+      );
+    }
+    return null;
+  }
+  return editScore({ score }, "setScore");
 }
 
 // src/share.ts
-function isDevelopment4() {
+function isDevelopment6() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow4() {
+function getBridgeWindow6() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge2(methodName) {
-  if (isDevelopment4()) {
+function warnMissingBridge4(methodName) {
+  if (isDevelopment6()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " share bridge is unavailable. This is expected in local development."
     );
@@ -1100,20 +1202,20 @@ function validateRequest(options) {
 }
 async function share(options) {
   const request = validateRequest(options);
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow6();
   if (typeof bridge?.__oasizShareRequest !== "function") {
-    warnMissingBridge2("__oasizShareRequest");
+    warnMissingBridge4("__oasizShareRequest");
     throw new Error("Share bridge unavailable");
   }
   await bridge.__oasizShareRequest(request);
 }
 
 // src/state.ts
-function isDevelopment5() {
+function isDevelopment7() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow5() {
+function getBridgeWindow7() {
   if (typeof window === "undefined") {
     return void 0;
   }
@@ -1126,22 +1228,22 @@ function isPlainObject(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function warnMissingBridge3(methodName) {
-  if (isDevelopment5()) {
+function warnMissingBridge5(methodName) {
+  if (isDevelopment7()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
 function loadGameState() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow7();
   if (typeof bridge?.loadGameState !== "function") {
-    warnMissingBridge3("loadGameState");
+    warnMissingBridge5("loadGameState");
     return {};
   }
   const state = bridge.loadGameState();
   if (!isPlainObject(state)) {
-    if (isDevelopment5()) {
+    if (isDevelopment7()) {
       console.warn(
         "[oasiz/sdk] loadGameState returned invalid data. Falling back to empty object."
       );
@@ -1152,35 +1254,35 @@ function loadGameState() {
 }
 function saveGameState(state) {
   if (!isPlainObject(state)) {
-    if (isDevelopment5()) {
+    if (isDevelopment7()) {
       console.warn("[oasiz/sdk] saveGameState expected a plain object:", state);
     }
     return;
   }
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow7();
   if (typeof bridge?.saveGameState === "function") {
     bridge.saveGameState(state);
     return;
   }
-  warnMissingBridge3("saveGameState");
+  warnMissingBridge5("saveGameState");
 }
 function flushGameState() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow7();
   if (typeof bridge?.flushGameState === "function") {
     bridge.flushGameState();
     return;
   }
-  warnMissingBridge3("flushGameState");
+  warnMissingBridge5("flushGameState");
 }
 
 // src/lifecycle.ts
-function isDevelopment6() {
+function isDevelopment8() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
 function addLifecycleListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment6()) {
+    if (isDevelopment8()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1200,46 +1302,74 @@ function onResume(callback) {
 }
 
 // src/layout.ts
-function isDevelopment7() {
+function isDevelopment9() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow6() {
+function getBridgeWindow8() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge4(methodName) {
-  if (isDevelopment7()) {
+function warnMissingBridge6(methodName) {
+  if (isDevelopment9()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
-function normalizeSafeAreaTop(value) {
+function normalizeSafeAreaTopPixels(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return 0;
   }
   return Math.max(0, value);
 }
+function normalizeSafeAreaTopPercent(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(100, Math.max(0, value));
+}
+function viewportInnerHeight(bridge) {
+  const h = bridge.innerHeight;
+  if (typeof h !== "number" || !Number.isFinite(h) || h <= 0) {
+    return 0;
+  }
+  return h;
+}
+function pixelsTopToPercentOfViewport(pixels, bridge) {
+  const h = viewportInnerHeight(bridge);
+  if (h <= 0) {
+    return 0;
+  }
+  return normalizeSafeAreaTopPercent(pixels / h * 100);
+}
 function getSafeAreaTop() {
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow8();
   if (!bridge) {
     return 0;
   }
+  if (typeof bridge.getSafeAreaTopPercent === "function") {
+    return normalizeSafeAreaTopPercent(bridge.getSafeAreaTopPercent());
+  }
+  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
+    return normalizeSafeAreaTopPercent(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__);
+  }
   if (typeof bridge.getSafeAreaTop === "function") {
-    return normalizeSafeAreaTop(bridge.getSafeAreaTop());
+    const px = normalizeSafeAreaTopPixels(bridge.getSafeAreaTop());
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
   if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
+    const px = normalizeSafeAreaTopPixels(bridge.__OASIZ_SAFE_AREA_TOP__);
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
-  warnMissingBridge4("getSafeAreaTop");
+  warnMissingBridge6("getSafeAreaTop");
   return 0;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
-    if (isDevelopment7()) {
+    if (isDevelopment9()) {
       console.warn(
         "[oasiz/sdk] setLeaderboardVisible expected a boolean:",
         visible
@@ -1247,28 +1377,28 @@ function setLeaderboardVisible(visible) {
     }
     return;
   }
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow8();
   if (typeof bridge?.__oasizSetLeaderboardVisible === "function") {
     bridge.__oasizSetLeaderboardVisible(visible);
     return;
   }
-  warnMissingBridge4("__oasizSetLeaderboardVisible");
+  warnMissingBridge6("__oasizSetLeaderboardVisible");
 }
 
 // src/navigation.ts
 var activeBackListeners = 0;
-function isDevelopment8() {
+function isDevelopment10() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow7() {
+function getBridgeWindow9() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge5(methodName) {
-  if (isDevelopment8()) {
+function warnMissingBridge7(methodName) {
+  if (isDevelopment10()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
@@ -1284,7 +1414,7 @@ function normalizeNavigationError(error) {
 }
 function addNavigationListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment8()) {
+    if (isDevelopment10()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1305,24 +1435,24 @@ function onBackButton(callback) {
       throw normalizeNavigationError(error);
     }
   });
-  const bridge = getBridgeWindow7();
+  const bridge = getBridgeWindow9();
   activeBackListeners += 1;
   if (activeBackListeners === 1) {
     if (typeof bridge?.__oasizSetBackOverride === "function") {
       bridge.__oasizSetBackOverride(true);
     } else {
-      warnMissingBridge5("__oasizSetBackOverride");
+      warnMissingBridge7("__oasizSetBackOverride");
     }
   }
   return () => {
     off();
     activeBackListeners = Math.max(0, activeBackListeners - 1);
     if (activeBackListeners === 0) {
-      const currentBridge = getBridgeWindow7();
+      const currentBridge = getBridgeWindow9();
       if (typeof currentBridge?.__oasizSetBackOverride === "function") {
         currentBridge.__oasizSetBackOverride(false);
       } else {
-        warnMissingBridge5("__oasizSetBackOverride");
+        warnMissingBridge7("__oasizSetBackOverride");
       }
     }
   };
@@ -1331,17 +1461,20 @@ function onLeaveGame(callback) {
   return addNavigationListener("oasiz:leave", callback);
 }
 function leaveGame() {
-  const bridge = getBridgeWindow7();
+  const bridge = getBridgeWindow9();
   if (typeof bridge?.__oasizLeaveGame === "function") {
     bridge.__oasizLeaveGame();
     return;
   }
-  warnMissingBridge5("__oasizLeaveGame");
+  warnMissingBridge7("__oasizLeaveGame");
 }
 
 // src/index.ts
 var oasiz = {
   submitScore,
+  addScore,
+  setScore,
+  getPlayerCharacter,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -1363,6 +1496,9 @@ var oasiz = {
   get roomCode() {
     return getRoomCode();
   },
+  get playerId() {
+    return getPlayerId();
+  },
   get playerName() {
     return getPlayerName();
   },
@@ -1375,10 +1511,13 @@ var oasiz = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  addScore,
   enableLogOverlay,
   flushGameState,
   getGameId,
   getPlayerAvatar,
+  getPlayerCharacter,
+  getPlayerId,
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
@@ -1392,6 +1531,7 @@ var oasiz = {
   openInviteModal,
   saveGameState,
   setLeaderboardVisible,
+  setScore,
   share,
   shareRoomCode,
   submitScore,