@oasiz/sdk 0.1.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @oasiz/sdk
 
-Typed SDK for Oasiz game bridge APIs.
+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.
 
 ## Install
 
@@ -8,35 +8,191 @@ Typed SDK for Oasiz game bridge APIs.
 npm install @oasiz/sdk
 ```
 
-## Usage
+## Quick start
 
 ```ts
-import { oasis } from "@oasiz/sdk";
+import { oasiz } from "@oasiz/sdk";
 
-oasis.emitScoreConfig({
-  anchors: [
-    { raw: 30, normalized: 100 },
-    { raw: 60, normalized: 300 },
-    { raw: 120, normalized: 600 },
-    { raw: 300, normalized: 950 },
-  ],
+// 1. Load persisted state at the start of each session
+const state = oasiz.loadGameState();
+let level = typeof state.level === "number" ? state.level : 1;
+
+// 2. Save state at checkpoints
+oasiz.saveGameState({ level, coins: 42 });
+
+// 3. Trigger haptics on key events
+oasiz.triggerHaptic("medium");
+
+// 4. Submit score when the game ends
+oasiz.submitScore(score);
+```
+
+---
+
+## Score
+
+### `oasiz.submitScore(score: number)`
+
+Submit the player's score. The platform handles leaderboard persistence — do not track high scores locally.
+
+```ts
+oasiz.submitScore(this.score);
+```
+
+- `score` must be a non-negative integer. Floats are floored automatically.
+- When and how often you call this depends on your game type (once at game over, end of each level, or throttled for long sessions).
+
+---
+
+## Haptics
+
+### `oasiz.triggerHaptic(type: HapticType)`
+
+Trigger native haptic feedback. Always guard with the user's haptics setting.
+
+```ts
+type HapticType = "light" | "medium" | "heavy" | "success" | "error";
+```
+
+| Type | When to use |
+|---|---|
+| `"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 |
+
+```ts
+button.addEventListener("click", () => {
+  oasiz.triggerHaptic("light");
 });
 
-const saved = oasis.loadGameState();
-oasis.saveGameState({ ...saved, level: 3 });
-oasis.triggerHaptic("light");
-oasis.submitScore(42);
+private onGameOver(): void {
+  oasiz.submitScore(this.score);
+  if (this.settings.haptics) {
+    oasiz.triggerHaptic("error");
+  }
+}
 ```
 
-## API
+---
+
+## Game state persistence
+
+Persist cross-session data such as unlocked levels, inventory, or lifetime stats. Available across devices and app reinstalls.
+
+### `oasiz.loadGameState(): Record<string, unknown>`
+
+Returns the player's saved state synchronously. Returns `{}` if no state has been saved yet.
+
+```ts
+const state = oasiz.loadGameState();
+this.level = typeof state.level === "number" ? state.level : 1;
+```
 
-- `submitScore(score)`
-- `emitScoreConfig(config)`
-- `triggerHaptic(type)`
-- `loadGameState()`
-- `saveGameState(state)`
-- `flushGameState()`
-- `shareRoomCode(code)`
-- `onPause(callback)`
-- `onResume(callback)`
-- `oasis.gameId`, `oasis.roomCode`, `oasis.playerName`, `oasis.playerAvatar`
+### `oasiz.saveGameState(state: Record<string, unknown>)`
+
+Queues a debounced save. Call freely at checkpoints.
+
+```ts
+oasiz.saveGameState({ level: this.level, unlockedSkins: this.unlockedSkins });
+```
+
+- State must be a plain JSON object (not an array or primitive).
+- Use `saveGameState` instead of `localStorage` for cross-session progress.
+- Do not store scores here — use `submitScore`.
+
+### `oasiz.flushGameState()`
+
+Forces an immediate write, bypassing the debounce. Use at game over or before page unload.
+
+```ts
+oasiz.saveGameState({ level: this.level });
+oasiz.flushGameState();
+oasiz.submitScore(this.score);
+```
+
+---
+
+## Lifecycle
+
+### `oasiz.onPause(callback: () => void): Unsubscribe`
+### `oasiz.onResume(callback: () => void): Unsubscribe`
+
+Both return an unsubscribe function.
+
+```ts
+const offPause = oasiz.onPause(() => {
+  this.gameLoop.stop();
+  this.bgMusic.pause();
+});
+
+const offResume = oasiz.onResume(() => {
+  this.gameLoop.start();
+  this.bgMusic.play();
+});
+
+offPause();
+offResume();
+```
+
+---
+
+## Multiplayer
+
+### `oasiz.shareRoomCode(code: string | null)`
+
+Notify the platform of the active multiplayer room. Pass `null` when leaving.
+
+```ts
+oasiz.shareRoomCode(getRoomCode());
+oasiz.shareRoomCode(null);
+```
+
+### Read-only properties
+
+| Property | Type | Description |
+|---|---|---|
+| `oasiz.gameId` | string \| undefined | The platform's game ID |
+| `oasiz.roomCode` | string \| undefined | Pre-filled room code from invite |
+| `oasiz.playerName` | string \| undefined | Player's display name |
+| `oasiz.playerAvatar` | string \| undefined | Player's profile picture URL |
+
+---
+
+## Named exports
+
+```ts
+import {
+  submitScore,
+  triggerHaptic,
+  loadGameState,
+  saveGameState,
+  flushGameState,
+  shareRoomCode,
+  onPause,
+  onResume,
+  getGameId,
+  getRoomCode,
+  getPlayerName,
+  getPlayerAvatar,
+} from "@oasiz/sdk";
+```
+
+---
+
+## TypeScript types
+
+```ts
+import type { HapticType, GameState } from "@oasiz/sdk";
+```
+
+---
+
+## Local development
+
+All methods safely no-op when the platform bridges are not injected. In development mode a console warning is logged:
+
+```
+[oasiz/sdk] submitScore bridge is unavailable. This is expected in local development.
+```

package/dist/index.cjs

@@ -20,14 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  emitScoreConfig: () => emitScoreConfig,
   flushGameState: () => flushGameState,
   getGameId: () => getGameId,
   getPlayerAvatar: () => getPlayerAvatar,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   loadGameState: () => loadGameState,
-  oasis: () => oasis,
+  oasiz: () => oasiz,
   onPause: () => onPause,
   onResume: () => onResume,
   saveGameState: () => saveGameState,
@@ -134,14 +133,6 @@ 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() {
@@ -235,9 +226,8 @@ function onResume(callback) {
 }
 
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -260,14 +250,13 @@ var oasis = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
   loadGameState,
-  oasis,
+  oasiz,
   onPause,
   onResume,
   saveGameState,

package/dist/index.d.cts

@@ -1,35 +1,245 @@
+/**
+ * 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";
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
+/**
+ * A plain JSON-serializable object used for cross-session game state
+ * persistence.
+ *
+ * @category State
+ */
 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;
 
-declare const oasis: {
+/**
+ * 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 const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -43,4 +253,4 @@ declare const oasis: {
     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 Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -1,35 +1,245 @@
+/**
+ * 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";
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
+/**
+ * A plain JSON-serializable object used for cross-session game state
+ * persistence.
+ *
+ * @category State
+ */
 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;
 
-declare const oasis: {
+/**
+ * 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 const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -43,4 +253,4 @@ declare const oasis: {
     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 Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.global.js

@@ -0,0 +1,252 @@
+"use strict";
+var oasiz = (() => {
+  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, {
+    flushGameState: () => flushGameState,
+    getGameId: () => getGameId,
+    getPlayerAvatar: () => getPlayerAvatar,
+    getPlayerName: () => getPlayerName,
+    getRoomCode: () => getRoomCode,
+    loadGameState: () => loadGameState,
+    oasiz: () => oasiz,
+    onPause: () => onPause,
+    onResume: () => onResume,
+    saveGameState: () => saveGameState,
+    shareRoomCode: () => shareRoomCode,
+    submitScore: () => submitScore,
+    triggerHaptic: () => triggerHaptic
+  });
+
+  // src/haptics.ts
+  function isDevelopment() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function getBridgeWindow() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function triggerHaptic(type) {
+    const bridge = getBridgeWindow();
+    if (typeof bridge?.triggerHaptic === "function") {
+      bridge.triggerHaptic(type);
+      return;
+    }
+    if (isDevelopment()) {
+      console.warn(
+        "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+
+  // src/multiplayer.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 shareRoomCode(roomCode) {
+    const bridge = getBridgeWindow2();
+    if (typeof bridge?.shareRoomCode === "function") {
+      bridge.shareRoomCode(roomCode);
+      return;
+    }
+    if (isDevelopment2()) {
+      console.warn(
+        "[oasiz/sdk] shareRoomCode bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function getGameId() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__GAME_ID__;
+  }
+  function getRoomCode() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__ROOM_CODE__;
+  }
+  function getPlayerName() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__PLAYER_NAME__;
+  }
+  function getPlayerAvatar() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__PLAYER_AVATAR__;
+  }
+
+  // src/score.ts
+  function isDevelopment3() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function warnMissingBridge(methodName) {
+    if (isDevelopment3()) {
+      console.warn(
+        "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function getBridgeWindow3() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function submitScore(score) {
+    if (!Number.isFinite(score)) {
+      if (isDevelopment3()) {
+        console.warn("[oasiz/sdk] submitScore expected a finite number:", score);
+      }
+      return;
+    }
+    const bridge = getBridgeWindow3();
+    const normalizedScore = Math.max(0, Math.floor(score));
+    if (typeof bridge?.submitScore === "function") {
+      bridge.submitScore(normalizedScore);
+      return;
+    }
+    warnMissingBridge("submitScore");
+  }
+
+  // src/state.ts
+  function isDevelopment4() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function getBridgeWindow4() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+  }
+  function warnMissingBridge2(methodName) {
+    if (isDevelopment4()) {
+      console.warn(
+        "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function loadGameState() {
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.loadGameState !== "function") {
+      warnMissingBridge2("loadGameState");
+      return {};
+    }
+    const state = bridge.loadGameState();
+    if (!isPlainObject(state)) {
+      if (isDevelopment4()) {
+        console.warn(
+          "[oasiz/sdk] loadGameState returned invalid data. Falling back to empty object."
+        );
+      }
+      return {};
+    }
+    return state;
+  }
+  function saveGameState(state) {
+    if (!isPlainObject(state)) {
+      if (isDevelopment4()) {
+        console.warn("[oasiz/sdk] saveGameState expected a plain object:", state);
+      }
+      return;
+    }
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.saveGameState === "function") {
+      bridge.saveGameState(state);
+      return;
+    }
+    warnMissingBridge2("saveGameState");
+  }
+  function flushGameState() {
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.flushGameState === "function") {
+      bridge.flushGameState();
+      return;
+    }
+    warnMissingBridge2("flushGameState");
+  }
+
+  // src/lifecycle.ts
+  function isDevelopment5() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function addLifecycleListener(eventName, callback) {
+    if (typeof window === "undefined") {
+      if (isDevelopment5()) {
+        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 onPause(callback) {
+    return addLifecycleListener("oasiz:pause", callback);
+  }
+  function onResume(callback) {
+    return addLifecycleListener("oasiz:resume", callback);
+  }
+
+  // src/index.ts
+  var oasiz = {
+    submitScore,
+    triggerHaptic,
+    loadGameState,
+    saveGameState,
+    flushGameState,
+    shareRoomCode,
+    onPause,
+    onResume,
+    get gameId() {
+      return getGameId();
+    },
+    get roomCode() {
+      return getRoomCode();
+    },
+    get playerName() {
+      return getPlayerName();
+    },
+    get playerAvatar() {
+      return getPlayerAvatar();
+    }
+  };
+  return __toCommonJS(index_exports);
+})();

package/dist/index.js

@@ -95,14 +95,6 @@ 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() {
@@ -196,9 +188,8 @@ function onResume(callback) {
 }
 
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -220,14 +211,13 @@ var oasis = {
   }
 };
 export {
-  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
   loadGameState,
-  oasis,
+  oasiz,
   onPause,
   onResume,
   saveGameState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -10,7 +10,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "script": "./dist/index.global.js"
     }
   },
   "files": [
@@ -18,9 +19,11 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts --format esm,cjs,iife --global-name oasiz --dts",
     "prepack": "bun run build",
-    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts"
+    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -28,12 +31,26 @@
   "release": {
     "branches": [
       "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/github",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "npm version ${nextRelease.version} --no-git-tag-version --allow-same-version --no-workspaces",
+          "publishCmd": "npm publish --access public --no-workspaces"
+        }
+      ]
     ]
   },
   "devDependencies": {
+    "@semantic-release/exec": "^7.1.0",
     "@types/node": "^25.3.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3"
   }
 }