@oasiz/sdk 1.6.0 → 1.6.2

package/dist/index.d.ts

@@ -1,10 +1,143 @@
+type GraphicsPerformanceTier = "minimal" | "low" | "medium" | "high";
+interface GraphicsPerformanceMetric {
+    /** Recommended graphics/rendering frame-rate target for the current device. */
+    fps: number;
+    /** Suggested graphics/rendering tier for the current device. */
+    tier: GraphicsPerformanceTier;
+}
+/**
+ * Return the current device's recommended graphics performance profile.
+ *
+ * Hosts can provide an FPS/tier recommendation through
+ * `window.getGraphicsPerformance()` or `window.__OASIZ_GRAPHICS_PERFORMANCE__`.
+ * When no host value exists, the SDK estimates from browser/device/WebGL
+ * capability signals so games still get a usable recommendation in local
+ * development and unsupported hosts.
+ */
+declare function getGraphicsPerformance(): GraphicsPerformanceMetric;
+
+type ViewportInsetSide = "top" | "right" | "bottom" | "left";
+interface ViewportInsetEdges {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface ViewportInsets {
+    pixels: ViewportInsetEdges;
+    percent: ViewportInsetEdges;
+}
+/**
+ * Effective viewport insets that game UI should avoid.
+ *
+ * `top` preserves the existing Oasiz game-safe top behavior: host chrome and
+ * invite/leaderboard clearance can contribute to it. Other sides are device
+ * safe-area insets today, and can include future host UI obstructions.
+ */
+declare function getViewportInsets(): ViewportInsets;
+/**
+ * Legacy alias for the top entry of `getViewportInsets().percent`.
+ */
+declare function getSafeAreaTop(): number;
+declare function setLeaderboardVisible(visible: boolean): void;
+
+type Unsubscribe = () => void;
+declare function onPause(callback: () => void): Unsubscribe;
+declare function onResume(callback: () => void): Unsubscribe;
+
+interface BackButtonTestingOptions {
+    /**
+     * When true, pressing Escape dispatches the same event the host app sends for
+     * back actions. Defaults to true.
+     */
+    keyboard?: boolean;
+    /**
+     * When true, the SDK traps one browser-history entry while back override is
+     * active, so the browser Back button can be used for local testing. Defaults
+     * to true.
+     */
+    browserHistory?: boolean;
+    /** Log setup details to the console. Defaults to false. */
+    log?: boolean;
+}
+interface BackButtonTestingHandle {
+    destroy: () => void;
+    isBackOverrideActive: () => boolean;
+    triggerBack: () => void;
+    triggerLeave: () => void;
+}
+declare function enableBackButtonTesting(options?: BackButtonTestingOptions): BackButtonTestingHandle;
+declare function onBackButton(callback: () => void): Unsubscribe;
+declare function onLeaveGame(callback: () => void): Unsubscribe;
+declare function leaveGame(): void;
+
+type AppSimulatorDeviceName = "iphone-11" | "iphone-11-pro" | "iphone-11-pro-max" | "iphone-12-mini" | "iphone-12" | "iphone-12-pro" | "iphone-12-pro-max" | "iphone-13-mini" | "iphone-13" | "iphone-13-pro" | "iphone-13-pro-max" | "iphone-14" | "iphone-14-plus" | "iphone-14-pro" | "iphone-14-pro-max" | "iphone-15" | "iphone-15-plus" | "iphone-15-pro" | "iphone-15-pro-max" | "iphone-16" | "iphone-16-plus" | "iphone-16-pro" | "iphone-16-pro-max" | "iphone-16e" | "iphone-17" | "iphone-17-pro" | "iphone-17-pro-max" | "iphone-17e" | "iphone-air" | "iphone-se" | "pixel-8";
+type AppSimulatorOrientation = "portrait" | "landscape";
+interface AppSimulatorDevice {
+    height: number;
+    name?: string;
+    safeArea?: Partial<ViewportInsetEdges>;
+    width: number;
+}
+interface AppSimulatorOptions {
+    browserHistoryBack?: BackButtonTestingOptions["browserHistory"];
+    comments?: number;
+    device?: AppSimulatorDeviceName | AppSimulatorDevice;
+    enabled?: boolean;
+    /**
+     * When true, the SDK tries to place the current game DOM inside a centered
+     * phone viewport on desktop. Use false if your game already runs in browser
+     * device emulation or owns its own preview frame. Defaults to true.
+     */
+    frame?: boolean | "auto";
+    keyboardBack?: BackButtonTestingOptions["keyboard"];
+    leaderboardVisible?: boolean;
+    likes?: number;
+    log?: boolean;
+    orientation?: AppSimulatorOrientation;
+    score?: number;
+    title?: string;
+}
+interface AppSimulatorHandle {
+    closeSheet: () => void;
+    destroy: () => void;
+    getViewportInsets: () => ViewportInsets;
+    hide: () => void;
+    isVisible: () => boolean;
+    openComments: () => void;
+    openLeaderboard: () => void;
+    setCounts: (counts: {
+        comments?: number;
+        likes?: number;
+    }) => void;
+    setLeaderboardVisible: (visible: boolean) => void;
+    setLiked: (liked: boolean) => void;
+    show: () => void;
+    triggerBack: () => void;
+    triggerLeave: () => void;
+}
+declare function enableAppSimulator(options?: AppSimulatorOptions): AppSimulatorHandle;
+
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
+type LogOverlayLevel = "debug" | "log" | "info" | "warn" | "error";
+interface LogOverlayEntry {
+    id: number;
+    level: LogOverlayLevel;
+    message: string;
+    timestamp: number;
 }
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
+interface LogOverlayOptions {
+    collapsed?: boolean;
+    enabled?: boolean;
+    maxEntries?: number;
+    title?: string;
+}
+interface LogOverlayHandle {
+    clear: () => void;
+    destroy: () => void;
+    hide: () => void;
+    isVisible: () => boolean;
+    show: () => void;
 }
 type GameState = Record<string, unknown>;
 interface ShareRequest {
@@ -12,88 +145,166 @@ interface ShareRequest {
     score?: number;
     text?: string;
 }
-type StoreProductType = "non-consumable" | "consumable";
-type StoreProductStatus = "active" | "disabled" | "archived";
-type StoreEntitlementStatus = "active" | "consumed" | "revoked" | "refunded";
-interface StoreManifestProduct {
-    description?: string | null;
-    jemPrice: number;
-    metadata?: Record<string, unknown>;
-    productId: string;
-    title: string;
-    type: StoreProductType;
-}
-interface StoreProduct {
-    description: string | null;
-    gameId: string;
-    jemPrice: number;
-    metadata: Record<string, unknown>;
-    productId: string;
-    status: StoreProductStatus;
-    title: string;
-    type: StoreProductType;
-    version: number;
-}
-interface StoreEntitlement {
-    gameId: string;
-    grantedAt: string | null;
-    lastEventId: string | null;
-    owned: boolean;
-    productId: string;
-    quantity: number;
-    status: StoreEntitlementStatus;
-    updatedAt: string;
-}
-interface StoreStateSnapshot {
-    catalogVersion: number;
-    entitlements: StoreEntitlement[];
-    gameId: string;
-    jemBalance: number;
-    products: StoreProduct[];
-}
-interface StorePurchaseSuccess {
-    attemptId: string;
-    entitlement: StoreEntitlement;
-    jemBalance: number;
-    ok: true;
-    state: StoreStateSnapshot;
-    transactionId: string;
-}
-interface StorePurchaseFailure {
-    attemptId: string;
-    code: "ALREADY_OWNED" | "INSUFFICIENT_JEMS" | "INVALID_PRODUCT" | "PRODUCT_DISABLED" | "INVALID_QUANTITY" | "ENTITLEMENT_EXHAUSTED" | "STALE_CATALOG_VERSION" | "UNAUTHORIZED";
-    jemBalance: number;
-    message: string;
-    ok: false;
-    state?: StoreStateSnapshot;
-    topUpIntentId?: string;
-    topUpRedirectUrl?: string;
-}
-type StorePurchaseResult = StorePurchaseSuccess | StorePurchaseFailure;
-interface StoreConsumeSuccess {
-    entitlement: StoreEntitlement;
-    ok: true;
-    state: StoreStateSnapshot;
-}
-interface StoreConsumeFailure {
-    code: "INVALID_PRODUCT" | "INVALID_QUANTITY" | "NOT_CONSUMABLE" | "ENTITLEMENT_EXHAUSTED";
-    jemBalance: number;
-    message: string;
-    ok: false;
-    state?: StoreStateSnapshot;
+/**
+ * One frame in a texture atlas. Coordinates are in pixels, top-left origin
+ * (matches HTML canvas / WebGL texture coordinates after Y-flip).
+ */
+interface TextureAtlasFrame {
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Per-direction frame indexes inside an animation. `left` is either an
+ * integer index or the literal string `"mirror"`, indicating the renderer
+ * should mirror the right-facing frame instead of using a dedicated one.
+ */
+interface FacingFrameMap {
+    front: number;
+    back: number;
+    right: number;
+    left: number | "mirror";
+}
+/**
+ * One named animation in a texture atlas. `frames` is the playback-ordered
+ * list of frame names; resolve each name against the parent atlas's
+ * `frames` array to get pixel coordinates.
+ */
+interface TextureAtlasAnimation {
+    animationId: string;
+    role: string | null;
+    group: string | null;
+    direction: string | null;
+    frameRate: number;
+    frames: string[];
+    facingFrameMap: FacingFrameMap | null;
+}
+/**
+ * TexturePacker / Phaser-style texture atlas describing a baked sprite
+ * image. Drop-in compatible with Phaser via `addAtlas(key, img, atlas)`
+ * after a tiny shape transform; usable directly in custom GL renderers.
+ */
+interface TextureAtlas {
+    imageUrl: string;
+    imageWidth: number;
+    imageHeight: number;
+    frames: TextureAtlasFrame[];
+    animations: TextureAtlasAnimation[];
 }
-type StoreConsumeResult = StoreConsumeSuccess | StoreConsumeFailure;
+/**
+ * The authenticated player's character, returned by `getPlayerCharacter()`.
+ * `editorTextureAtlas` is the higher-detail variant intended for character
+ * previews / customizer UI and may be `null`.
+ */
+interface PlayerCharacter {
+    characterName: string | null;
+    baseCharacterId: string;
+    compositionCode: string;
+    textureAtlas: TextureAtlas;
+    editorTextureAtlas: TextureAtlas | null;
+}
+/**
+ * Result of `addScore(delta)` / `setScore(score)`. Returns `null` when the
+ * host bridge is unavailable (e.g. local development) or when the backend
+ * refused the request; production code should treat `null` as "no change
+ * was persisted, do not update local UI".
+ */
+interface ScoreEditResult {
+    playerId: string;
+    previousScore: number;
+    newScore: number;
+    previousWeeklyScore: number;
+    newWeeklyScore: number;
+    normalizedScore: number | null;
+}
+
+/**
+ * Fetch the authenticated player's character, including a TexturePacker /
+ * Phaser-style texture atlas describing the baked sprite image.
+ *
+ * Returns:
+ *   - `null` when the user has no character composition yet, OR
+ *   - `null` when the host bridge is unavailable (local dev / unauthenticated)
+ *
+ * The host transparently caches and proxies to `GET /api/sdk/me/character`,
+ * so calling this multiple times in a session is cheap. The returned
+ * `imageUrl` is content-addressed (R2 key derives from the composition
+ * hash), so games can safely cache the downloaded texture by `compositionCode`.
+ *
+ * Example (Phaser):
+ *
+ *   const character = await oasiz.getPlayerCharacter();
+ *   if (!character) return;
+ *   const atlas = character.textureAtlas;
+ *   scene.load.image("player-tex", atlas.imageUrl);
+ *   scene.load.atlas("player", atlas.imageUrl, {
+ *     frames: Object.fromEntries(
+ *       atlas.frames.map((f) => [f.name, { frame: { x: f.x, y: f.y, w: f.width, h: f.height } }]),
+ *     ),
+ *   });
+ */
+declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
-declare function shareRoomCode(roomCode: string | null): void;
+declare function enableLogOverlay(options?: LogOverlayOptions): LogOverlayHandle;
+
+interface ShareRoomCodeOptions {
+    inviteOverride?: boolean;
+}
+/**
+ * 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, options?: ShareRoomCodeOptions): void;
+/**
+ * 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;
 declare function getRoomCode(): string | undefined;
+/**
+ * Stable, unique, opaque identifier for the authenticated player, injected
+ * by the platform. Safe to use as a primary key for save slots, matchmaking,
+ * per-player analytics, or anywhere you need a reliable per-user key —
+ * unlike `getPlayerName()` (mutable, not unique).
+ *
+ * Mirrors the backend's `playerId` field returned by `GET /api/sdk/me`
+ * (= the Better Auth `user.id`). Returns `undefined` when the platform
+ * has not injected an identity (e.g. unauthenticated preview).
+ */
+declare function getPlayerId(): string | undefined;
 declare function getPlayerName(): string | undefined;
 declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
-declare function emitScoreConfig(config: ScoreConfig): void;
+
+/**
+ * Add (or subtract) `delta` from the player's current score for this game.
+ * The new score is clamped to >= 0 server-side.
+ *
+ * Unlike `submitScore()` (which is high-water and only ever raises the
+ * score), this endpoint always overwrites the row. Use it for game models
+ * where the leaderboard tracks an accumulator, balance, or persistent state
+ * instead of a single best-run value.
+ *
+ * Returns the resulting score values, or `null` when the bridge is
+ * unavailable. The integer must be a non-zero integer (positive or negative).
+ */
+declare function addScore(delta: number): Promise<ScoreEditResult | null>;
+/**
+ * Force the player's score to an absolute value (clamped to >= 0).
+ *
+ * Same overwrite semantics as `addScore`. Use when the game has computed
+ * the authoritative score locally (e.g. after offline play) and wants to
+ * sync it back to the leaderboard.
+ */
+declare function setScore(score: number): Promise<ScoreEditResult | null>;
 
 declare function share(options: ShareRequest): Promise<void>;
 
@@ -101,55 +312,38 @@ declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
 
-type Unsubscribe = () => void;
-declare function onPause(callback: () => void): Unsubscribe;
-declare function onResume(callback: () => void): Unsubscribe;
-
-declare function onBackButton(callback: () => void): Unsubscribe;
-declare function onLeaveGame(callback: () => void): Unsubscribe;
-declare function leaveGame(): void;
-
-declare function syncProducts(products: StoreManifestProduct[], expectedVersion?: number | null): Promise<StoreStateSnapshot>;
-declare function getProducts(): Promise<StoreProduct[]>;
-declare function getEntitlements(): Promise<StoreEntitlement[]>;
-declare function hasEntitlement(productId: string): Promise<boolean>;
-declare function getQuantity(productId: string): Promise<number>;
-declare function purchase(productId: string, quantity?: number): Promise<StorePurchaseResult>;
-declare function consume(productId: string, quantity?: number): Promise<StoreConsumeResult>;
-declare function getJemBalance(): Promise<number>;
-declare function onEntitlementsChanged(callback: (entitlements: StoreEntitlement[]) => void): () => void;
-declare function onJemBalanceChanged(callback: (jemBalance: number) => void): () => void;
-
 declare const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
+    enableAppSimulator: typeof enableAppSimulator;
+    addScore: typeof addScore;
+    setScore: typeof setScore;
+    getPlayerCharacter: typeof getPlayerCharacter;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
+    enableLogOverlay: typeof enableLogOverlay;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
     flushGameState: typeof flushGameState;
     shareRoomCode: typeof shareRoomCode;
+    openInviteModal: typeof openInviteModal;
     onPause: typeof onPause;
     onResume: typeof onResume;
+    getSafeAreaTop: typeof getSafeAreaTop;
+    getViewportInsets: typeof getViewportInsets;
+    setLeaderboardVisible: typeof setLeaderboardVisible;
+    getGraphicsPerformance: typeof getGraphicsPerformance;
+    enableBackButtonTesting: typeof enableBackButtonTesting;
     onBackButton: typeof onBackButton;
     onLeaveGame: typeof onLeaveGame;
     leaveGame: typeof leaveGame;
-    store: {
-        syncProducts: typeof syncProducts;
-        getProducts: typeof getProducts;
-        getEntitlements: typeof getEntitlements;
-        hasEntitlement: typeof hasEntitlement;
-        getQuantity: typeof getQuantity;
-        purchase: typeof purchase;
-        consume: typeof consume;
-        getJemBalance: typeof getJemBalance;
-        onEntitlementsChanged: typeof onEntitlementsChanged;
-        onJemBalanceChanged: typeof onJemBalanceChanged;
-    };
     readonly gameId: string | undefined;
     readonly roomCode: string | undefined;
+    readonly playerId: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
+    readonly safeAreaTop: number;
+    readonly viewportInsets: ViewportInsets;
+    readonly graphicsPerformance: GraphicsPerformanceMetric;
 };
 
-export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type ShareRequest, type StoreConsumeFailure, type StoreConsumeResult, type StoreConsumeSuccess, type StoreEntitlement, type StoreEntitlementStatus, type StoreManifestProduct, type StoreProduct, type StoreProductStatus, type StoreProductType, type StorePurchaseFailure, type StorePurchaseResult, type StorePurchaseSuccess, type StoreStateSnapshot, type Unsubscribe, consume, emitScoreConfig, flushGameState, getEntitlements, getGameId, getJemBalance, getPlayerAvatar, getPlayerName, getProducts, getQuantity, getRoomCode, hasEntitlement, leaveGame, loadGameState, oasiz, onBackButton, onEntitlementsChanged, onJemBalanceChanged, onLeaveGame, onPause, onResume, purchase, saveGameState, share, shareRoomCode, submitScore, syncProducts, triggerHaptic };
+export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };