@oasiz/sdk 1.5.6 → 1.6.0

package/dist/index.d.cts

@@ -1,48 +1,10 @@
-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 HapticType = "light" | "medium" | "heavy" | "success" | "error";
-type LogOverlayLevel = "debug" | "log" | "info" | "warn" | "error";
-interface LogOverlayEntry {
-    id: number;
-    level: LogOverlayLevel;
-    message: string;
-    timestamp: number;
+interface ScoreAnchor {
+    raw: number;
+    normalized: 100 | 300 | 600 | 950;
 }
-interface LogOverlayOptions {
-    collapsed?: boolean;
-    enabled?: boolean;
-    maxEntries?: number;
-    title?: string;
-}
-interface LogOverlayHandle {
-    clear: () => void;
-    destroy: () => void;
-    hide: () => void;
-    isVisible: () => boolean;
-    show: () => void;
+interface ScoreConfig {
+    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
 }
 type GameState = Record<string, unknown>;
 interface ShareRequest {
@@ -50,166 +12,88 @@ interface ShareRequest {
     score?: number;
     text?: string;
 }
-/**
- * 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;
+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;
 }
-/**
- * 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";
+interface StoreProduct {
+    description: string | null;
+    gameId: string;
+    jemPrice: number;
+    metadata: Record<string, unknown>;
+    productId: string;
+    status: StoreProductStatus;
+    title: string;
+    type: StoreProductType;
+    version: number;
 }
-/**
- * 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;
+interface StoreEntitlement {
+    gameId: string;
+    grantedAt: string | null;
+    lastEventId: string | null;
+    owned: boolean;
+    productId: string;
+    quantity: number;
+    status: StoreEntitlementStatus;
+    updatedAt: string;
 }
-/**
- * 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[];
+interface StoreStateSnapshot {
+    catalogVersion: number;
+    entitlements: StoreEntitlement[];
+    gameId: string;
+    jemBalance: number;
+    products: StoreProduct[];
 }
-/**
- * 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;
+interface StorePurchaseSuccess {
+    attemptId: string;
+    entitlement: StoreEntitlement;
+    jemBalance: number;
+    ok: true;
+    state: StoreStateSnapshot;
+    transactionId: string;
 }
-/**
- * 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;
+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;
 }
-
-/**
- * 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>;
+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;
+}
+type StoreConsumeResult = StoreConsumeSuccess | StoreConsumeFailure;
 
 declare function triggerHaptic(type: HapticType): 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 shareRoomCode(roomCode: string | null): 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;
-
-/**
- * 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 emitScoreConfig(config: ScoreConfig): void;
 
 declare function share(options: ShareRequest): Promise<void>;
 
@@ -225,34 +109,47 @@ 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;
-    addScore: typeof addScore;
-    setScore: typeof setScore;
-    getPlayerCharacter: typeof getPlayerCharacter;
+    emitScoreConfig: typeof emitScoreConfig;
     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;
     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;
 };
 
-export { type FacingFrameMap, type GameState, 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, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+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 };