@oasiz/sdk 1.0.1 → 1.0.2

package/dist/index.d.cts

@@ -1,245 +1,39 @@
-/**
- * Intensity level for native haptic feedback.
- *
- * | Type        | Use case                                        |
- * |-------------|-------------------------------------------------|
- * | `"light"`   | UI button taps, menu navigation, D-pad press    |
- * | `"medium"`  | Collecting items, standard collisions, scoring   |
- * | `"heavy"`   | Explosions, major impacts, screen shake          |
- * | `"success"` | Level complete, achievement unlocked             |
- * | `"error"`   | Damage taken, game over, invalid action          |
- *
- * @category Haptics
- */
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
-/**
- * A plain JSON-serializable object used for cross-session game state
- * persistence.
- *
- * @category State
- */
+interface ScoreAnchor {
+    raw: number;
+    normalized: 100 | 300 | 600 | 950;
+}
+interface ScoreConfig {
+    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
+}
 type GameState = Record<string, unknown>;
 
-/**
- * Trigger native haptic feedback on the player's device.
- *
- * Always guard calls with the user's haptics preference toggle.
- * The bridge is a no-op in local development (a console warning is logged).
- *
- * @param type - The haptic intensity level.
- *
- * @example
- * ```ts
- * // UI button tap
- * oasiz.triggerHaptic("light");
- *
- * // Tiered hit feedback
- * oasiz.triggerHaptic(isPerfectHit ? "success" : "medium");
- *
- * // Game over
- * oasiz.triggerHaptic("error");
- * ```
- *
- * @category Haptics
- */
 declare function triggerHaptic(type: HapticType): void;
 
-/**
- * Notify the platform of the active multiplayer room so friends can join
- * via the invite system. Pass `null` when leaving a room.
- *
- * @param roomCode - The room code string, or `null` to clear.
- *
- * @example
- * ```ts
- * import { insertCoin, getRoomCode } from "playroomkit";
- *
- * await insertCoin({ skipLobby: true });
- * oasiz.shareRoomCode(getRoomCode());
- *
- * // On disconnect
- * oasiz.shareRoomCode(null);
- * ```
- *
- * @category Multiplayer
- */
 declare function shareRoomCode(roomCode: string | null): void;
-/**
- * Get the platform's internal game ID, injected before the game loads.
- *
- * @returns The game ID string, or `undefined` if not yet injected.
- *
- * @category Multiplayer
- */
 declare function getGameId(): string | undefined;
-/**
- * Get the pre-filled room code for auto-joining a friend's multiplayer session.
- *
- * @returns The room code string, or `undefined` if not in a multiplayer context.
- *
- * @category Multiplayer
- */
 declare function getRoomCode(): string | undefined;
-/**
- * Get the current player's display name, injected by the platform.
- *
- * @returns The player name, or `undefined` if not available.
- *
- * @category Multiplayer
- */
 declare function getPlayerName(): string | undefined;
-/**
- * Get the current player's avatar URL, injected by the platform.
- *
- * @returns The avatar URL string, or `undefined` if not available.
- *
- * @category Multiplayer
- */
 declare function getPlayerAvatar(): string | undefined;
 
-/**
- * Submit the player's score.
- *
- * The platform handles leaderboard persistence — do not track high scores locally.
- *
- * - `score` must be a finite number. Floats are floored, negatives are clamped to 0.
- * - In development mode a console warning is logged when the bridge is unavailable.
- *
- * @param score - The player's score (non-negative integer).
- *
- * @example
- * ```ts
- * oasiz.submitScore(Math.floor(this.score));
- * ```
- *
- * @category Score
- */
 declare function submitScore(score: number): void;
+declare function emitScoreConfig(config: ScoreConfig): void;
 
-/**
- * Load the player's persisted game state.
- *
- * Returns the saved state synchronously. Returns `{}` if no state has been
- * saved yet or if the bridge is unavailable. Always validate the shape of
- * the returned data — it may be empty on first play.
- *
- * Call once at the start of the game.
- *
- * @returns The player's saved {@link GameState}, or an empty object.
- *
- * @example
- * ```ts
- * const state = oasiz.loadGameState();
- * this.level = typeof state.level === "number" ? state.level : 1;
- * ```
- *
- * @category State
- */
 declare function loadGameState(): GameState;
-/**
- * Queue a debounced save of the player's game state.
- *
- * Saves are batched automatically — call freely at checkpoints without
- * worrying about request spam. State must be a plain JSON-serializable object.
- *
- * @param state - A plain object to persist. Do not pass arrays or primitives.
- *
- * @example
- * ```ts
- * oasiz.saveGameState({
- *   level: this.level,
- *   lifetimeHits: this.lifetimeHits,
- *   unlockedSkins: this.unlockedSkins,
- * });
- * ```
- *
- * @category State
- */
 declare function saveGameState(state: GameState): void;
-/**
- * Force an immediate write of the pending game state, bypassing the debounce.
- *
- * Use at critical checkpoints like game over or before the page unloads
- * to ensure data is persisted.
- *
- * @example
- * ```ts
- * oasiz.saveGameState({ level: this.level });
- * oasiz.flushGameState(); // ensure it lands before the page closes
- * oasiz.submitScore(this.score);
- * ```
- *
- * @category State
- */
 declare function flushGameState(): void;
 
-/**
- * A function that removes an event listener when called.
- * Returned by {@link onPause} and {@link onResume}.
- *
- * @category Lifecycle
- */
 type Unsubscribe = () => void;
-/**
- * Register a callback that fires when the app goes to the background.
- *
- * Use this to pause game loops, audio, and animations so the game
- * doesn't continue running while the player is away.
- *
- * @param callback - Invoked when the platform dispatches `oasiz:pause`.
- * @returns An {@link Unsubscribe} function that removes the listener.
- *
- * @example
- * ```ts
- * const off = oasiz.onPause(() => {
- *   this.gameLoop.stop();
- *   this.bgMusic.pause();
- * });
- *
- * // Later, clean up:
- * off();
- * ```
- *
- * @category Lifecycle
- */
 declare function onPause(callback: () => void): Unsubscribe;
-/**
- * Register a callback that fires when the app returns to the foreground.
- *
- * Use this to resume game loops, audio, and animations after a pause.
- *
- * @param callback - Invoked when the platform dispatches `oasiz:resume`.
- * @returns An {@link Unsubscribe} function that removes the listener.
- *
- * @example
- * ```ts
- * const off = oasiz.onResume(() => {
- *   this.gameLoop.start();
- *   this.bgMusic.play();
- * });
- *
- * // Later, clean up:
- * off();
- * ```
- *
- * @category Lifecycle
- */
 declare function onResume(callback: () => void): Unsubscribe;
 
-/**
- * The main SDK namespace object. Provides convenient access to all
- * platform bridge APIs as a single import.
- *
- * @example
- * ```ts
- * import { oasiz } from "@oasiz/sdk";
- *
- * oasiz.triggerHaptic("medium");
- * oasiz.submitScore(score);
- * ```
- */
+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;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -247,10 +41,13 @@ declare const oasiz: {
     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 Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, 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

@@ -1,245 +1,39 @@
-/**
- * Intensity level for native haptic feedback.
- *
- * | Type        | Use case                                        |
- * |-------------|-------------------------------------------------|
- * | `"light"`   | UI button taps, menu navigation, D-pad press    |
- * | `"medium"`  | Collecting items, standard collisions, scoring   |
- * | `"heavy"`   | Explosions, major impacts, screen shake          |
- * | `"success"` | Level complete, achievement unlocked             |
- * | `"error"`   | Damage taken, game over, invalid action          |
- *
- * @category Haptics
- */
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
-/**
- * A plain JSON-serializable object used for cross-session game state
- * persistence.
- *
- * @category State
- */
+interface ScoreAnchor {
+    raw: number;
+    normalized: 100 | 300 | 600 | 950;
+}
+interface ScoreConfig {
+    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
+}
 type GameState = Record<string, unknown>;
 
-/**
- * Trigger native haptic feedback on the player's device.
- *
- * Always guard calls with the user's haptics preference toggle.
- * The bridge is a no-op in local development (a console warning is logged).
- *
- * @param type - The haptic intensity level.
- *
- * @example
- * ```ts
- * // UI button tap
- * oasiz.triggerHaptic("light");
- *
- * // Tiered hit feedback
- * oasiz.triggerHaptic(isPerfectHit ? "success" : "medium");
- *
- * // Game over
- * oasiz.triggerHaptic("error");
- * ```
- *
- * @category Haptics
- */
 declare function triggerHaptic(type: HapticType): void;
 
-/**
- * Notify the platform of the active multiplayer room so friends can join
- * via the invite system. Pass `null` when leaving a room.
- *
- * @param roomCode - The room code string, or `null` to clear.
- *
- * @example
- * ```ts
- * import { insertCoin, getRoomCode } from "playroomkit";
- *
- * await insertCoin({ skipLobby: true });
- * oasiz.shareRoomCode(getRoomCode());
- *
- * // On disconnect
- * oasiz.shareRoomCode(null);
- * ```
- *
- * @category Multiplayer
- */
 declare function shareRoomCode(roomCode: string | null): void;
-/**
- * Get the platform's internal game ID, injected before the game loads.
- *
- * @returns The game ID string, or `undefined` if not yet injected.
- *
- * @category Multiplayer
- */
 declare function getGameId(): string | undefined;
-/**
- * Get the pre-filled room code for auto-joining a friend's multiplayer session.
- *
- * @returns The room code string, or `undefined` if not in a multiplayer context.
- *
- * @category Multiplayer
- */
 declare function getRoomCode(): string | undefined;
-/**
- * Get the current player's display name, injected by the platform.
- *
- * @returns The player name, or `undefined` if not available.
- *
- * @category Multiplayer
- */
 declare function getPlayerName(): string | undefined;
-/**
- * Get the current player's avatar URL, injected by the platform.
- *
- * @returns The avatar URL string, or `undefined` if not available.
- *
- * @category Multiplayer
- */
 declare function getPlayerAvatar(): string | undefined;
 
-/**
- * Submit the player's score.
- *
- * The platform handles leaderboard persistence — do not track high scores locally.
- *
- * - `score` must be a finite number. Floats are floored, negatives are clamped to 0.
- * - In development mode a console warning is logged when the bridge is unavailable.
- *
- * @param score - The player's score (non-negative integer).
- *
- * @example
- * ```ts
- * oasiz.submitScore(Math.floor(this.score));
- * ```
- *
- * @category Score
- */
 declare function submitScore(score: number): void;
+declare function emitScoreConfig(config: ScoreConfig): void;
 
-/**
- * Load the player's persisted game state.
- *
- * Returns the saved state synchronously. Returns `{}` if no state has been
- * saved yet or if the bridge is unavailable. Always validate the shape of
- * the returned data — it may be empty on first play.
- *
- * Call once at the start of the game.
- *
- * @returns The player's saved {@link GameState}, or an empty object.
- *
- * @example
- * ```ts
- * const state = oasiz.loadGameState();
- * this.level = typeof state.level === "number" ? state.level : 1;
- * ```
- *
- * @category State
- */
 declare function loadGameState(): GameState;
-/**
- * Queue a debounced save of the player's game state.
- *
- * Saves are batched automatically — call freely at checkpoints without
- * worrying about request spam. State must be a plain JSON-serializable object.
- *
- * @param state - A plain object to persist. Do not pass arrays or primitives.
- *
- * @example
- * ```ts
- * oasiz.saveGameState({
- *   level: this.level,
- *   lifetimeHits: this.lifetimeHits,
- *   unlockedSkins: this.unlockedSkins,
- * });
- * ```
- *
- * @category State
- */
 declare function saveGameState(state: GameState): void;
-/**
- * Force an immediate write of the pending game state, bypassing the debounce.
- *
- * Use at critical checkpoints like game over or before the page unloads
- * to ensure data is persisted.
- *
- * @example
- * ```ts
- * oasiz.saveGameState({ level: this.level });
- * oasiz.flushGameState(); // ensure it lands before the page closes
- * oasiz.submitScore(this.score);
- * ```
- *
- * @category State
- */
 declare function flushGameState(): void;
 
-/**
- * A function that removes an event listener when called.
- * Returned by {@link onPause} and {@link onResume}.
- *
- * @category Lifecycle
- */
 type Unsubscribe = () => void;
-/**
- * Register a callback that fires when the app goes to the background.
- *
- * Use this to pause game loops, audio, and animations so the game
- * doesn't continue running while the player is away.
- *
- * @param callback - Invoked when the platform dispatches `oasiz:pause`.
- * @returns An {@link Unsubscribe} function that removes the listener.
- *
- * @example
- * ```ts
- * const off = oasiz.onPause(() => {
- *   this.gameLoop.stop();
- *   this.bgMusic.pause();
- * });
- *
- * // Later, clean up:
- * off();
- * ```
- *
- * @category Lifecycle
- */
 declare function onPause(callback: () => void): Unsubscribe;
-/**
- * Register a callback that fires when the app returns to the foreground.
- *
- * Use this to resume game loops, audio, and animations after a pause.
- *
- * @param callback - Invoked when the platform dispatches `oasiz:resume`.
- * @returns An {@link Unsubscribe} function that removes the listener.
- *
- * @example
- * ```ts
- * const off = oasiz.onResume(() => {
- *   this.gameLoop.start();
- *   this.bgMusic.play();
- * });
- *
- * // Later, clean up:
- * off();
- * ```
- *
- * @category Lifecycle
- */
 declare function onResume(callback: () => void): Unsubscribe;
 
-/**
- * The main SDK namespace object. Provides convenient access to all
- * platform bridge APIs as a single import.
- *
- * @example
- * ```ts
- * import { oasiz } from "@oasiz/sdk";
- *
- * oasiz.triggerHaptic("medium");
- * oasiz.submitScore(score);
- * ```
- */
+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;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -247,10 +41,13 @@ declare const oasiz: {
     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 Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, 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

@@ -95,6 +95,14 @@ function submitScore(score) {
   }
   warnMissingBridge("submitScore");
 }
+function emitScoreConfig(config) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.emitScoreConfig === "function") {
+    bridge.emitScoreConfig(config);
+    return;
+  }
+  warnMissingBridge("emitScoreConfig");
+}
 
 // src/state.ts
 function isDevelopment4() {
@@ -187,9 +195,79 @@ 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 oasiz = {
   submitScore,
+  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -197,6 +275,9 @@ var oasiz = {
   shareRoomCode,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   get gameId() {
     return getGameId();
   },
@@ -211,13 +292,17 @@ var oasiz = {
   }
 };
 export {
+  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  leaveGame,
   loadGameState,
   oasiz,
+  onBackButton,
+  onLeaveGame,
   onPause,
   onResume,
   saveGameState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -10,8 +10,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "script": "./dist/index.global.js"
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -19,11 +18,9 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs,iife --global-name oasiz --dts",
+    "build": "tsup src/index.ts --format esm,cjs --dts",
     "prepack": "bun run build",
-    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts",
-    "docs": "typedoc",
-    "docs:watch": "typedoc --watch"
+    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -50,7 +47,6 @@
     "@types/node": "^25.3.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
-    "typedoc": "^0.28.17",
     "typescript": "^5.9.3"
   }
 }