@oasiz/sdk 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -1,256 +1,68 @@
-/**
- * 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;
 
+interface ShareRoomCodeOptions {
+    inviteOverride?: boolean;
+}
 /**
- * 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
+ * Notify the platform of the active multiplayer room so friends can join.
+ * Pass `{ inviteOverride: true }` when the game wants to hide the platform
+ * invite pill and own the invite UI itself.
  */
-declare function shareRoomCode(roomCode: string | null): void;
+declare function shareRoomCode(roomCode: string | null, options?: ShareRoomCodeOptions): 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
+ * Ask the platform to open the invite-friends modal for the current game room.
+ * Only has effect when the platform has a room code (game has called shareRoomCode).
+ * No-op when the bridge is unavailable (e.g. local development).
  */
+declare function openInviteModal(): void;
 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;
     flushGameState: typeof flushGameState;
     shareRoomCode: typeof shareRoomCode;
+    openInviteModal: typeof openInviteModal;
     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 ShareRoomCodeOptions, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -1,256 +1,68 @@
-/**
- * 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;
 
+interface ShareRoomCodeOptions {
+    inviteOverride?: boolean;
+}
 /**
- * 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
+ * Notify the platform of the active multiplayer room so friends can join.
+ * Pass `{ inviteOverride: true }` when the game wants to hide the platform
+ * invite pill and own the invite UI itself.
  */
-declare function shareRoomCode(roomCode: string | null): void;
+declare function shareRoomCode(roomCode: string | null, options?: ShareRoomCodeOptions): 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
+ * Ask the platform to open the invite-friends modal for the current game room.
+ * Only has effect when the platform has a room code (game has called shareRoomCode).
+ * No-op when the bridge is unavailable (e.g. local development).
  */
+declare function openInviteModal(): void;
 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;
     flushGameState: typeof flushGameState;
     shareRoomCode: typeof shareRoomCode;
+    openInviteModal: typeof openInviteModal;
     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 ShareRoomCodeOptions, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, shareRoomCode, submitScore, triggerHaptic };