@oasiz/sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @oasiz/sdk
 
-Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, and app lifecycle events for local development.
+Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, navigation hooks, and app lifecycle events for local development.
 
 ## Install
 
@@ -209,6 +209,55 @@ offResume();
 
 ---
 
+## Navigation
+
+Use navigation hooks when your game needs to control back behavior (Android back / web Escape) or participate in host-driven close events.
+
+### `oasiz.onBackButton(callback: () => void): Unsubscribe`
+
+Registers a callback for platform back actions. While at least one back listener is subscribed, back actions are routed to your game instead of immediately closing it.
+
+Use this for pause menus, in-game overlays, or custom back-stack behavior.
+
+```ts
+const offBack = oasiz.onBackButton(() => {
+  if (this.isPauseMenuOpen) {
+    this.closePauseMenu();
+    return;
+  }
+  this.openPauseMenu();
+});
+
+// Restore default host back behavior when no longer needed
+offBack();
+```
+
+### `oasiz.leaveGame(): void`
+
+Programmatically request the host to close the current game (for example, from a Quit button inside your game UI).
+
+```ts
+quitButton.addEventListener("click", () => {
+  oasiz.leaveGame();
+});
+```
+
+### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
+
+Registers a callback fired when the host initiates closing the game (for example, close button, gesture, or host navigation). Use this for lightweight cleanup.
+
+```ts
+const offLeave = oasiz.onLeaveGame(() => {
+  oasiz.flushGameState();
+  this.bgMusic.pause();
+});
+
+// Clean up listener when destroyed
+offLeave();
+```
+
+---
+
 ## Multiplayer
 
 ### `oasiz.shareRoomCode(code: string | null)`
@@ -261,6 +310,9 @@ import {
   shareRoomCode,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   getGameId,
   getRoomCode,
   getPlayerName,

package/dist/index.cjs

@@ -26,8 +26,11 @@ __export(index_exports, {
   getPlayerAvatar: () => getPlayerAvatar,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
+  leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
-  oasis: () => oasis,
+  oasiz: () => oasiz,
+  onBackButton: () => onBackButton,
+  onLeaveGame: () => onLeaveGame,
   onPause: () => onPause,
   onResume: () => onResume,
   saveGameState: () => saveGameState,
@@ -234,8 +237,77 @@ function onResume(callback) {
   return addLifecycleListener("oasiz:resume", callback);
 }
 
+// src/navigation.ts
+var activeBackListeners = 0;
+function isDevelopment6() {
+  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 (isDevelopment6()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function addNavigationListener(eventName, callback) {
+  if (typeof window === "undefined") {
+    if (isDevelopment6()) {
+      console.warn(
+        "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
+      );
+    }
+    return () => {
+    };
+  }
+  const handler = () => callback();
+  window.addEventListener(eventName, handler);
+  return () => window.removeEventListener(eventName, handler);
+}
+function onBackButton(callback) {
+  const off = addNavigationListener("oasiz:back", callback);
+  const bridge = getBridgeWindow5();
+  activeBackListeners += 1;
+  if (activeBackListeners === 1) {
+    if (typeof bridge?.__oasizSetBackOverride === "function") {
+      bridge.__oasizSetBackOverride(true);
+    } else {
+      warnMissingBridge3("__oasizSetBackOverride");
+    }
+  }
+  return () => {
+    off();
+    activeBackListeners = Math.max(0, activeBackListeners - 1);
+    if (activeBackListeners === 0) {
+      const currentBridge = getBridgeWindow5();
+      if (typeof currentBridge?.__oasizSetBackOverride === "function") {
+        currentBridge.__oasizSetBackOverride(false);
+      } else {
+        warnMissingBridge3("__oasizSetBackOverride");
+      }
+    }
+  };
+}
+function onLeaveGame(callback) {
+  return addNavigationListener("oasiz:leave", callback);
+}
+function leaveGame() {
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizLeaveGame === "function") {
+    bridge.__oasizLeaveGame();
+    return;
+  }
+  warnMissingBridge3("__oasizLeaveGame");
+}
+
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
   emitScoreConfig,
   triggerHaptic,
@@ -245,6 +317,9 @@ var oasis = {
   shareRoomCode,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   get gameId() {
     return getGameId();
   },
@@ -266,8 +341,11 @@ var oasis = {
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  leaveGame,
   loadGameState,
-  oasis,
+  oasiz,
+  onBackButton,
+  onLeaveGame,
   onPause,
   onResume,
   saveGameState,

package/dist/index.d.cts

@@ -27,7 +27,11 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
-declare const oasis: {
+declare function onBackButton(callback: () => void): Unsubscribe;
+declare function onLeaveGame(callback: () => void): Unsubscribe;
+declare function leaveGame(): void;
+
+declare const oasiz: {
     submitScore: typeof submitScore;
     emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
@@ -37,10 +41,13 @@ declare const oasis: {
     shareRoomCode: typeof shareRoomCode;
     onPause: typeof onPause;
     onResume: typeof onResume;
+    onBackButton: typeof onBackButton;
+    onLeaveGame: typeof onLeaveGame;
+    leaveGame: typeof leaveGame;
     readonly gameId: string | undefined;
     readonly roomCode: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
 };
 
-export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasis, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -27,7 +27,11 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
-declare const oasis: {
+declare function onBackButton(callback: () => void): Unsubscribe;
+declare function onLeaveGame(callback: () => void): Unsubscribe;
+declare function leaveGame(): void;
+
+declare const oasiz: {
     submitScore: typeof submitScore;
     emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
@@ -37,10 +41,13 @@ declare const oasis: {
     shareRoomCode: typeof shareRoomCode;
     onPause: typeof onPause;
     onResume: typeof onResume;
+    onBackButton: typeof onBackButton;
+    onLeaveGame: typeof onLeaveGame;
+    leaveGame: typeof leaveGame;
     readonly gameId: string | undefined;
     readonly roomCode: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
 };
 
-export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasis, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.js

@@ -195,8 +195,77 @@ function onResume(callback) {
   return addLifecycleListener("oasiz:resume", callback);
 }
 
+// src/navigation.ts
+var activeBackListeners = 0;
+function isDevelopment6() {
+  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 (isDevelopment6()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function addNavigationListener(eventName, callback) {
+  if (typeof window === "undefined") {
+    if (isDevelopment6()) {
+      console.warn(
+        "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
+      );
+    }
+    return () => {
+    };
+  }
+  const handler = () => callback();
+  window.addEventListener(eventName, handler);
+  return () => window.removeEventListener(eventName, handler);
+}
+function onBackButton(callback) {
+  const off = addNavigationListener("oasiz:back", callback);
+  const bridge = getBridgeWindow5();
+  activeBackListeners += 1;
+  if (activeBackListeners === 1) {
+    if (typeof bridge?.__oasizSetBackOverride === "function") {
+      bridge.__oasizSetBackOverride(true);
+    } else {
+      warnMissingBridge3("__oasizSetBackOverride");
+    }
+  }
+  return () => {
+    off();
+    activeBackListeners = Math.max(0, activeBackListeners - 1);
+    if (activeBackListeners === 0) {
+      const currentBridge = getBridgeWindow5();
+      if (typeof currentBridge?.__oasizSetBackOverride === "function") {
+        currentBridge.__oasizSetBackOverride(false);
+      } else {
+        warnMissingBridge3("__oasizSetBackOverride");
+      }
+    }
+  };
+}
+function onLeaveGame(callback) {
+  return addNavigationListener("oasiz:leave", callback);
+}
+function leaveGame() {
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizLeaveGame === "function") {
+    bridge.__oasizLeaveGame();
+    return;
+  }
+  warnMissingBridge3("__oasizLeaveGame");
+}
+
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
   emitScoreConfig,
   triggerHaptic,
@@ -206,6 +275,9 @@ var oasis = {
   shareRoomCode,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   get gameId() {
     return getGameId();
   },
@@ -226,8 +298,11 @@ export {
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  leaveGame,
   loadGameState,
-  oasis,
+  oasiz,
+  onBackButton,
+  onLeaveGame,
   onPause,
   onResume,
   saveGameState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",