@playdotfun/game-sdk 1.0.0

package/src/sdk/index.ts

@@ -0,0 +1,1488 @@
+import { ApiClient } from '@/http/client';
+import {
+  PaginatedFetchOpts,
+  RecursivePartial,
+  SDKOpts,
+  SDKState,
+  Token,
+  Game,
+  SDKActions,
+  SDKEvents,
+  Theme,
+  SDKMessages,
+  Context,
+  WidgetScreen,
+  ListUserRewardsResponse,
+  ClaimRewardsResponse,
+  FlushState,
+  FlushResponse,
+  CommitResponse,
+  SessionStateResponse,
+} from '@/types';
+import { decodePointsObf, encodePointsObf } from './obfuscation';
+import { hmacSha256, generateUUID } from './crypto';
+import messaging from './messaging';
+import { WidgetBridge } from '@/widget/bridge';
+import { handleWidgetMessage } from '@/widget/messages';
+import config, { isDevOrigin } from '@/config';
+import { handleCarouselMessages } from '@/carousel/messages';
+import {
+  DashboardActions,
+  DashboardMessages,
+  DashboardScreens,
+  UpwardsDashboardActions,
+} from '@play-fun/types/sdk';
+import { DashboardBridge } from '@/dashboard/bridge';
+
+interface ReplicateAuthData {
+  gameId: string;
+  playerId: string;
+  identityToken?: string;
+  privyAccessToken?: string;
+}
+
+export default class OpenGameSDK {
+  private api: ApiClient;
+  private baseUrl: string = config.apiURL;
+
+  private state: SDKState;
+
+  private _widget: WidgetBridge | null = null;
+
+  private eventHandler: EventTarget = new EventTarget();
+
+  private messaging = messaging(this.eventHandler);
+
+  private _pendingLoginCallback: ((args?: any) => void) | null = null;
+
+  private _isInitializing: boolean = false;
+  private _pendingReplicateAuth: ReplicateAuthData | null = null;
+  private _replicateAuthResolver: ((data: ReplicateAuthData) => void) | null = null;
+
+  // Debug: unique instance ID to track if SDK is being recreated
+  private _instanceId = Math.random().toString(36).substring(2, 8);
+
+  // Rate limiting: track last savePoints call time
+  private _lastSavePointsTime: number = 0;
+
+  // Flush protocol state
+  private _flushState: FlushState = {
+    seq: 0,
+    currentHash: '',
+    stepKey: '',
+    totalPoints: 0,
+    initialized: false,
+  };
+  private _pointsBuffer: number = 0;
+  private _localTotal: number = 0;
+  private _flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private _clientInstanceId: string = this._getOrCreateClientInstanceId();
+  private _flushInProgress: boolean = false;
+
+  // Privy token refresh state
+  private _privyTokenResolvers: Map<string, (token: string) => void> = new Map();
+
+  /**
+   * Get or create a client instance ID that persists across page refreshes within the same tab.
+   * Uses sessionStorage so:
+   * - Same tab, page refresh → same ID (legitimate)
+   * - New tab → new ID (detected as multi-tab if same session)
+   */
+  private _getOrCreateClientInstanceId(): string {
+    const STORAGE_KEY = 'ogp_client_instance_id';
+    try {
+      const existing = sessionStorage.getItem(STORAGE_KEY);
+      if (existing) {
+        return existing;
+      }
+      const newId = generateUUID();
+      sessionStorage.setItem(STORAGE_KEY, newId);
+      return newId;
+    } catch {
+      // sessionStorage not available (e.g., private browsing in some browsers)
+      return generateUUID();
+    }
+  }
+
+  emit = this.messaging.emit;
+  on = this.messaging.on;
+  off = this.messaging.off;
+  onAll = this.messaging.onAll;
+
+  constructor(private readonly opts: SDKOpts) {
+    console.log(`[OpenGameSDK:${this._instanceId}] Creating new SDK instance`);
+    const {
+      apiKey = this._deriveApiKey(),
+      gameId = this._deriveGameId(),
+      playerId,
+      ui = { theme: 'system', usePointsWidget: true, useCustomUi: false },
+      isDashboard = false,
+    } = opts;
+
+    this.baseUrl = (opts.baseUrl || this.baseUrl).replace(/\/+$/, '');
+
+    const detectedDashboard = this._detectDashboardMode();
+    console.log(`[OpenGameSDK:${this._instanceId}] Detected dashboard mode:`, detectedDashboard);
+    const effectiveIsDashboard = isDashboard || detectedDashboard;
+
+    if (detectedDashboard && !isDashboard) {
+      console.log('[OpenGameSDK] Auto-detected dashboard mode from parent window');
+    }
+
+    this.api = new ApiClient({
+      baseUrl: this.baseUrl,
+    });
+
+    this.state = {
+      isReady: false,
+      apiKey,
+      gameId,
+      playerId,
+      ui,
+      isDashboard: effectiveIsDashboard,
+      dashboardUrl: config.dashboardURL,
+    };
+  }
+
+  /**
+   * Detect if the SDK is running inside the dashboard by checking parent window.
+   * Uses document.referrer since we can't access cross-origin parent location directly.
+   */
+  private _detectDashboardMode(): boolean {
+    if (window.parent === window) {
+      return false;
+    }
+    const params = new URLSearchParams(window.location.search);
+
+    const inCarousel = params.get('inCarousel') === 'true';
+    const inDashboard = params.get('inDashboard') === 'true';
+
+    if (inCarousel) {
+      return false;
+    }
+
+    if (inDashboard) {
+      return true;
+    }
+
+    try {
+      const referrer = document.referrer;
+      if (referrer) {
+        const referrerOrigin = new URL(referrer).origin;
+        const dashboardOrigin = new URL(config.dashboardURL).origin;
+        if (referrerOrigin === dashboardOrigin) {
+          return true;
+        }
+      }
+
+      try {
+        const parentOrigin = window.parent.location.origin;
+        const dashboardOrigin = new URL(config.dashboardURL).origin;
+        if (parentOrigin === dashboardOrigin) {
+          return true;
+        }
+      } catch {}
+    } catch (e) {
+      console.warn('[OpenGameSDK] Error detecting dashboard mode:', e);
+    }
+
+    return false;
+  }
+
+  private async fetchTokens(tokenIds: string[]) {
+    if (tokenIds.length === 0) {
+      return [];
+    }
+    try {
+      return await this.getTokens(tokenIds);
+    } catch (error) {
+      console.warn('[OpenGameSDK] Failed to fetch token data, returning empty array:', error);
+      return [];
+    }
+  }
+
+  async init(args?: { gameId?: string }) {
+    console.log('[OpenGameSDK] Initializing SDK...');
+    const { gameId } = args ?? {};
+    this._isInitializing = true;
+
+    if (gameId !== undefined && gameId !== this.state.gameId) {
+      this.state.gameId = gameId;
+      this.state.game = undefined;
+    }
+
+    try {
+      if (this.state.isDashboard && window.parent !== window) {
+        this._setupDashboardBridge();
+
+        console.debug(
+          '[OpenGameSDK] Dashboard mode: signaling ready and waiting for ReplicateAuth...',
+        );
+
+        if (this.opts.ui?.usePointsWidget || !this.opts.ui?.useCustomUI) {
+          console.log(`[OpenGameSDK] Initializing SDK Widget Bridge...`);
+          this._widget = new WidgetBridge((msg) => handleWidgetMessage(this, msg));
+
+          const url = this.getWidgetUrl();
+          await this._widget.init(document.body, url);
+          console.log('[OpenGameSDK] Widget Bridge Initialized Successfully!');
+        }
+        this._sendReadyToDashboard();
+        const authData = await this._waitForReplicateAuth(30_000);
+
+        if (authData) {
+          this.state.gameId = authData.gameId;
+          this.state.playerId = authData.playerId;
+          if (authData.identityToken) {
+            this.state.identityToken = authData.identityToken;
+          }
+          if (authData.privyAccessToken) {
+            this.state.privyAccessToken = authData.privyAccessToken;
+          }
+        }
+      } else if (window.parent !== window) {
+        console.log(`[OpenGameSDK] Initializing SDK Widget Bridge (embed mode)...`);
+        this._widget = new WidgetBridge((msg) => handleWidgetMessage(this, msg));
+
+        const url = this.getWidgetUrl();
+        await this._widget.init(document.body, url);
+        console.log('[OpenGameSDK] Widget Bridge Initialized Successfully!');
+      } else {
+        if (this.opts.ui?.usePointsWidget || !this.opts.ui?.useCustomUI) {
+          console.log(`[OpenGameSDK] Initializing SDK Widget Bridge...`);
+          this._widget = new WidgetBridge((msg) => handleWidgetMessage(this, msg));
+
+          const url = this.getWidgetUrl();
+          await this._widget.init(document.body, url);
+          console.log('[OpenGameSDK] Widget Bridge Initialized Successfully!');
+        }
+      }
+
+      let points = 0;
+      let tokens: Token[] = this.state.pointsDisplay?.tokens ?? [];
+      let activeMultiplier = 1;
+      let game: Game | undefined;
+
+      if (this.state.gameId) {
+        const hasPrivyAuth = !!this.state.privyAccessToken;
+        const [_game, sessionToken] = await Promise.all([
+          this.getGame(this.state.gameId),
+          hasPrivyAuth
+            ? this.getSessionToken(this.state.apiKey, this.state.gameId)
+            : Promise.resolve(null),
+        ]);
+
+        if (_game) {
+          game = _game;
+        }
+
+        if (sessionToken) {
+          this.state.session = { token: sessionToken, updatedAt: Date.now() };
+          this.updateAndReplicate({
+            session: { token: sessionToken, updatedAt: Date.now() },
+          });
+        }
+
+        // Determine which tokens to fetch
+        const tokenAddresses = Object.keys(_game?.tokenSplits ?? {});
+        const filteredTokens = tokenAddresses.filter((t) => t !== '__GAMECOIN_PLACEHOLDER__');
+        const needsTokenFetch = filteredTokens.length > 0;
+
+        // Parallel fetch: tokens and points (now that we have session and game data)
+        const [fetchedTokens, pointsData] = await Promise.all([
+          needsTokenFetch ? this.getTokens(filteredTokens) : Promise.resolve([]),
+          hasPrivyAuth ? this.getPoints() : Promise.resolve({ points: '0', activeMultiplier: 1 }),
+        ]);
+
+        tokens = fetchedTokens;
+        if (pointsData.points) {
+          points = parseInt(pointsData.points);
+        }
+        if (
+          pointsData.activeMultiplier &&
+          typeof pointsData.activeMultiplier === 'number' &&
+          pointsData.activeMultiplier > 0
+        ) {
+          activeMultiplier = pointsData.activeMultiplier;
+        }
+      }
+
+      if (!gameId || !this.state.gameId || !this.state.playerId) {
+        console.warn(
+          '[OpenGameSDK] No gameId or playerId found on initialization. Please pass a gameId and playerId to the SDK constructor to initialize with a valid session. Or call loadGame() instead of init() to load a new game session.',
+        );
+      }
+
+      this._setupCarouselBridge();
+
+      this.updateAndReplicate({
+        isReady: true,
+        game,
+        pointsDisplay: {
+          show: true,
+          points,
+          activeMultiplier,
+          tokens,
+        },
+      });
+
+      this.emit(SDKEvents.OnReady);
+      console.log('[OpenGameSDK] SDK Initialized Successfully');
+    } finally {
+      this._isInitializing = false;
+      // Clear any pending auth since we've completed init
+      this._pendingReplicateAuth = null;
+    }
+  }
+
+  /**
+   * Wait for ReplicateAuth message with a timeout.
+   * Returns the auth data if received, or null if timeout.
+   */
+  private async _waitForReplicateAuth(timeoutMs: number): Promise<ReplicateAuthData | null> {
+    // Check if we already have pending auth data
+    if (this._pendingReplicateAuth) {
+      console.log('[OpenGameSDK] Using already received auth data');
+      const data = this._pendingReplicateAuth;
+      this._pendingReplicateAuth = null;
+      return data;
+    }
+
+    // Wait for auth data with timeout
+    return new Promise<ReplicateAuthData | null>((resolve) => {
+      const timeout = setTimeout(() => {
+        console.log('[OpenGameSDK] Timeout waiting for ReplicateAuth');
+        this._replicateAuthResolver = null;
+        resolve(null);
+      }, timeoutMs);
+
+      this._replicateAuthResolver = (data: ReplicateAuthData) => {
+        clearTimeout(timeout);
+        resolve(data);
+      };
+
+      // Check again in case data arrived while setting up
+      if (this._pendingReplicateAuth) {
+        clearTimeout(timeout);
+        this._replicateAuthResolver = null;
+        const data = this._pendingReplicateAuth;
+        this._pendingReplicateAuth = null;
+        resolve(data);
+      }
+    });
+  }
+
+  /** Public Helper Methods */
+  async loadGame(gameId: string, playerId: string, privyAccessToken?: string) {
+    // Only skip if we have matching IDs AND a valid session token
+    const hasValidSession = !!this.state.session?.token;
+    if (this.state.gameId === gameId && this.state.playerId === playerId && hasValidSession) {
+      return;
+    }
+
+    // Set privyAccessToken if provided (needed for auth header in getSessionToken)
+    if (privyAccessToken) {
+      this.state.privyAccessToken = privyAccessToken;
+    }
+
+    // Parallel fetch: session token and game data (both only need gameId)
+    // Note: playerId parameter is deprecated - server returns canonical playerId from auth
+    const needsGameFetch = this.state.game?.id !== gameId;
+    const [token, game] = await Promise.all([
+      this.getSessionToken(this.state.apiKey, gameId),
+      needsGameFetch ? this.getGame(gameId) : Promise.resolve(this.state.game),
+    ]);
+
+    if (!game) {
+      throw new Error(`Game ${gameId} not found`);
+    }
+
+    this.state.session = { token, updatedAt: Date.now() };
+
+    const tokenAddresses = Object.keys(game?.tokenSplits ?? {});
+    const filteredTokens = tokenAddresses.filter((t) => t !== '__GAMECOIN_PLACEHOLDER__');
+    const needsTokenFetch = filteredTokens.length > 0;
+
+    const [_tokens, pointsData] = await Promise.all([
+      needsTokenFetch ? this.getTokens(filteredTokens) : Promise.resolve([]),
+      this.getPoints(),
+    ]);
+
+    const { points, activeMultiplier } = pointsData;
+
+    this.updateAndReplicate({
+      gameId,
+      game,
+      // playerId is set by getSessionToken from server response
+      session: { token, updatedAt: Date.now() },
+      pointsDisplay: {
+        show: this.ui?.usePointsWidget ?? true,
+        points: parseInt(points),
+        activeMultiplier,
+        tokens: _tokens,
+      },
+    });
+
+    if (this._pendingLoginCallback) {
+      this.widget?.sendMessage({
+        action: SDKActions.UI_ShowScreen,
+        data: {
+          screen: WidgetScreen.Loading,
+        },
+      });
+      const callback = this._pendingLoginCallback;
+      this._pendingLoginCallback = null;
+      callback();
+    }
+  }
+
+  async addPoints(points: number) {
+    this._checkReady();
+    if (!this.state.gameId) {
+      throw new Error(
+        'Must have an active game ID to add points. Please call init or loadGame first.',
+      );
+    }
+
+    // Initialize flush state if needed
+    if (!this._flushState.initialized && this.hasSession) {
+      await this._initFlushState();
+    }
+
+    // Add to local buffer
+    this._pointsBuffer += points;
+    this._localTotal += points;
+
+    // Update UI immediately (optimistic)
+    const activeMultiplier = this.state.pointsDisplay?.activeMultiplier ?? 1;
+    const multipliedPoints = Math.floor(points * activeMultiplier);
+    const newDisplayPoints = (this.state.pointsDisplay?.points ?? 0) + multipliedPoints;
+
+    // Also update legacy sessionPoints for backwards compatibility
+    const sessionPoints = this.state.sessionPoints ? decodePointsObf(this.state.sessionPoints) : 0;
+    const newSessionPoints = encodePointsObf(sessionPoints + points);
+
+    this.updateAndReplicate({
+      sessionPoints: newSessionPoints,
+      pointsDisplay: {
+        ...this.state.pointsDisplay,
+        points: newDisplayPoints,
+      },
+    });
+
+    // Schedule flush
+    this._scheduleFlush();
+  }
+
+  async decrPoints(points: number) {
+    this._checkReady();
+    if (!this.state.gameId) {
+      throw new Error(
+        'Must have an active game ID to decrease points. Please call init or loadGame first.',
+      );
+    }
+
+    // Decrease from buffer (can go negative for deductions)
+    this._pointsBuffer = Math.max(0, this._pointsBuffer - points);
+    this._localTotal = Math.max(0, this._localTotal - points);
+
+    const sessionPoints = this.state.sessionPoints ? decodePointsObf(this.state.sessionPoints) : 0;
+    const newSessionPoints = Math.max(0, sessionPoints - points);
+    const encodedSessionPoints = encodePointsObf(newSessionPoints);
+
+    const activeMultiplier = this.state.pointsDisplay?.activeMultiplier ?? 1;
+    const multipliedPoints = Math.floor(points * activeMultiplier);
+    const newDisplayPoints = Math.max(
+      0,
+      (this.state.pointsDisplay?.points ?? 0) - multipliedPoints,
+    );
+
+    this.updateAndReplicate({
+      sessionPoints: encodedSessionPoints,
+      pointsDisplay: {
+        ...this.state.pointsDisplay,
+        points: newDisplayPoints,
+      },
+    });
+  }
+
+  /**
+   * Initialize flush state by fetching from server.
+   */
+  private async _initFlushState(): Promise<void> {
+    if (this._flushState.initialized) return;
+
+    try {
+      const response = await this.fetch<SessionStateResponse>(
+        '/play/session-state',
+        { method: 'GET' },
+        true,
+      );
+
+      this._flushState = {
+        seq: response.lastSeq,
+        currentHash: response.lastHash,
+        stepKey: response.stepKey,
+        totalPoints: response.totalPoints,
+        initialized: true,
+      };
+
+      console.log(`[OpenGameSDK:${this._instanceId}] Flush state initialized:`, {
+        seq: this._flushState.seq,
+        totalPoints: this._flushState.totalPoints,
+      });
+    } catch (error) {
+      console.error('[OpenGameSDK] Failed to initialize flush state:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Schedule a flush to happen after a delay.
+   */
+  private _scheduleFlush(): void {
+    if (this._flushTimer) return;
+    this._flushTimer = setTimeout(() => this._flush(), 5000); // 5 second delay
+  }
+
+  /**
+   * Flush buffered points to server.
+   */
+  private async _flush(): Promise<void> {
+    this._flushTimer = null;
+    if (this._pointsBuffer <= 0 || this._flushInProgress) return;
+    if (!this.hasSession) return;
+
+    // Initialize flush state if needed
+    if (!this._flushState.initialized) {
+      try {
+        await this._initFlushState();
+      } catch (error) {
+        console.error('[OpenGameSDK] Failed to init flush state during flush:', error);
+        this._scheduleFlush(); // Retry later
+        return;
+      }
+    }
+
+    this._flushInProgress = true;
+    const pointsToFlush = this._pointsBuffer;
+    this._pointsBuffer = 0;
+    const nextSeq = this._flushState.seq + 1;
+
+    try {
+      // Compute proof with current step key
+      const sessionKey = `${this.state.playerId}:${this.state.gameId}`;
+      const proofData = `${sessionKey}|${nextSeq}|${pointsToFlush}|${this._flushState.currentHash}`;
+      const proof = await hmacSha256(this._flushState.stepKey, proofData);
+
+      const result = await this.fetch<FlushResponse>(
+        '/play/flush',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            seq: nextSeq,
+            points: pointsToFlush,
+            prevHash: this._flushState.currentHash,
+            proof,
+            clientInstanceId: this._clientInstanceId,
+          }),
+        },
+        true,
+      );
+
+      // Update state with server response
+      this._flushState.seq = result.seq;
+      this._flushState.currentHash = result.newHash;
+      this._flushState.stepKey = result.nextStepKey;
+      this._flushState.totalPoints = result.total;
+
+      console.log(`[OpenGameSDK:${this._instanceId}] Flush successful:`, {
+        seq: result.seq,
+        added: result.added,
+        total: result.total,
+      });
+
+      // Reconcile if server total differs significantly
+      if (Math.abs(result.total - this._localTotal) > pointsToFlush) {
+        console.warn(
+          `[OpenGameSDK] Points reconciliation needed: local=${this._localTotal}, server=${result.total}`,
+        );
+        this._localTotal = result.total;
+      }
+    } catch (error: any) {
+      console.error('[OpenGameSDK] Flush failed:', error);
+      // Re-add to buffer on failure
+      this._pointsBuffer += pointsToFlush;
+      // Retry after delay
+      this._scheduleFlush();
+    } finally {
+      this._flushInProgress = false;
+    }
+  }
+
+  async savePoints() {
+    this._checkReady();
+
+    // Rate limit: only allow savePoints once every 5 seconds
+    const now = Date.now();
+    const timeSinceLastSave = now - this._lastSavePointsTime;
+    if (timeSinceLastSave < 5000) {
+      const remainingTime = Math.ceil((5000 - timeSinceLastSave) / 1000);
+      throw new Error(
+        `Rate limit exceeded. Please wait ${remainingTime} more second(s) before saving points again.`,
+      );
+    }
+    this._lastSavePointsTime = now;
+
+    console.log(
+      `[OpenGameSDK:${this._instanceId}] savePoints called, hasSession:`,
+      this.hasSession,
+    );
+    if (!this.hasSession) {
+      console.log(
+        `[OpenGameSDK:${this._instanceId}] No session, setting _pendingLoginCallback and triggering login`,
+      );
+      this._pendingLoginCallback = () => this.savePoints();
+      await this.login();
+      console.log(
+        `[OpenGameSDK:${this._instanceId}] login() returned, _pendingLoginCallback is:`,
+        !!this._pendingLoginCallback,
+      );
+      return;
+    }
+
+    // Check if we have points to save (either in buffer, flush state, or legacy sessionPoints)
+    const hasLegacyPoints = this.state.sessionPoints && decodePointsObf(this.state.sessionPoints) > 0;
+    const hasBufferedPoints = this._pointsBuffer > 0 || this._flushState.totalPoints > 0;
+
+    if (!hasLegacyPoints && !hasBufferedPoints) {
+      throw new Error(
+        'No session points to save. Use addPoints() to accumulate points before saving.',
+      );
+    }
+
+    const callbackId = Math.random().toString(36).substring(2, 15);
+
+    if (!this.isDashboard && this.widget) {
+      this.widget?.sendMessage({
+        action: SDKActions.UI_ShowScreen,
+        data: {
+          screen: WidgetScreen.Loading,
+        },
+      });
+    } else if (this.isDashboard) {
+      DashboardBridge.sendMessage({
+        action: UpwardsDashboardActions.TriggerNotification,
+        data: {
+          title: 'Saving Points...',
+          callbackId,
+          type: 'promise',
+        },
+      });
+    }
+
+    try {
+      // Flush any remaining buffer first
+      if (this._pointsBuffer > 0) {
+        // Cancel scheduled flush and flush immediately
+        if (this._flushTimer) {
+          clearTimeout(this._flushTimer);
+          this._flushTimer = null;
+        }
+        await this._flush();
+      }
+
+      // Wait for any in-progress flush to complete
+      while (this._flushInProgress) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+
+      const pointsBeforeCommit = this._flushState.totalPoints || this._localTotal;
+
+      // Commit the accumulated points
+      const result = await this.fetch<CommitResponse>(
+        '/play/commit',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            seq: this._flushState.seq,
+            prevHash: this._flushState.currentHash,
+            referrer: this.state.referral?.referrerId,
+            distributors: this.state.distributorKeys,
+          }),
+        },
+        true,
+      );
+
+      console.log(`[OpenGameSDK:${this._instanceId}] Commit successful:`, result);
+
+      // Reset flush state for next session
+      this._flushState = {
+        seq: 0,
+        currentHash: '',
+        stepKey: '',
+        totalPoints: 0,
+        initialized: false,
+      };
+      this._pointsBuffer = 0;
+      this._localTotal = 0;
+
+      // Get updated points from server
+      const { points } = await this.getPoints();
+      this.updateAndReplicate({
+        sessionPoints: undefined,
+        pointsDisplay: {
+          ...this.state.pointsDisplay,
+          points: parseInt(points),
+        },
+      });
+
+      if (!this.state.ui?.useCustomUI) {
+        if (!this.isDashboard && this.widget) {
+          return this._widget?.sendMessage({
+            action: SDKActions.UI_ShowScreen,
+            data: {
+              screen: WidgetScreen.BoostPoints,
+              opts: {
+                points: pointsBeforeCommit,
+              },
+            },
+          });
+        } else if (this.isDashboard) {
+          DashboardBridge.sendMessage({
+            action: UpwardsDashboardActions.NotificationPromiseResult,
+            data: {
+              callbackId,
+              result: true,
+              title: 'Points saved successfully!',
+            },
+          });
+          return DashboardBridge.sendMessage({
+            action: UpwardsDashboardActions.ShowScreen,
+            data: {
+              screen: DashboardScreens.BoostPoints,
+              opts: {
+                points: pointsBeforeCommit,
+              },
+            },
+          });
+        }
+      }
+
+      return result;
+    } catch (e) {
+      console.error('[OpenGameSDK] Error saving points:', e);
+      const { points } = await this.getPoints();
+      if (points) {
+        this.updateAndReplicate({
+          pointsDisplay: {
+            ...this.state.pointsDisplay,
+            points: parseInt(points),
+          },
+        });
+      }
+      if (!this.state.ui?.useCustomUI) {
+        if (!this.isDashboard && this.widget) {
+          return this._widget?.sendMessage({
+            action: SDKActions.UI_ShowScreen,
+            data: {
+              screen: WidgetScreen.Error,
+              opts: {
+                error: e,
+              },
+            },
+          });
+        } else if (this.isDashboard) {
+          DashboardBridge.sendMessage({
+            action: UpwardsDashboardActions.NotificationPromiseResult,
+            data: {
+              callbackId,
+              result: false,
+              title: 'An error occurred while saving points',
+            },
+          });
+        }
+      }
+    }
+  }
+
+  async showClaim() {
+    this._checkReady();
+    if (!this.state.isEmbedSession && !this.isDashboard && this._widget) {
+      return this._widget.sendMessage({
+        action: SDKActions.UI_ShowScreen,
+        data: {
+          screen: WidgetScreen.Claim,
+          opts: {},
+        },
+      });
+    } else if (this.isDashboard) {
+      return DashboardBridge.sendMessage({
+        action: UpwardsDashboardActions.ShowScreen,
+        data: {
+          screen: DashboardScreens.Claim,
+          opts: {},
+        },
+      });
+    } else {
+      throw new Error('Cannot show claim screen outside of widget or dashboard mode.');
+    }
+  }
+
+  async login(callback?: string) {
+    this._checkReady();
+    if (!this.state.isEmbedSession && !this.isDashboard && this._widget) {
+      return this._widget.sendMessage({
+        action: SDKActions.UI_ShowScreen,
+        data: {
+          screen: WidgetScreen.Login,
+          opts: {
+            callback,
+          },
+        },
+      });
+    } else if (this.isDashboard) {
+      return DashboardBridge.sendMessage({
+        action: UpwardsDashboardActions.TriggerLogin,
+        data: undefined,
+      });
+    }
+    return this._sendMessageToCarousel({
+      action: SDKActions.TriggerPrivyLogin,
+      data: undefined,
+    });
+  }
+
+  /** API Methods */
+  async getGame(gameId: string) {
+    return await this.fetch<Game>(`/games/id/${gameId}?include_extra=true`);
+  }
+
+  async getGames({ ...opts }: PaginatedFetchOpts) {
+    return await this.paginatedFetch<Game>('/games', opts);
+  }
+
+  async getToken(tokenId: string) {
+    return await this.fetch<Token>(`/tokens/${tokenId}`);
+  }
+
+  async getTokens(tokenIds: string[]) {
+    return await this.fetch<Token[]>(`/tokens/?query=${tokenIds.join(',')}`);
+  }
+
+  async getPoints() {
+    return await this.fetch<{ points: string; activeMultiplier: number }>(
+      '/play/get-points',
+      { method: 'GET' },
+      true,
+    );
+  }
+
+  async listUserRewards() {
+    return await this.fetch<ListUserRewardsResponse>('/play/rewards', { method: 'GET' }, true);
+  }
+
+  async claimRewards(addresses: string[]) {
+    return await this.fetch<ClaimRewardsResponse>(
+      `/play/claim-rewards`,
+      {
+        method: 'POST',
+        body: JSON.stringify({ addresses }),
+      },
+      true,
+    );
+  }
+
+  setIdentityToken(token: string) {
+    this.updateAndReplicate({
+      identityToken: token,
+    });
+  }
+
+  setReferrer(referrerId: string, refferredGameId: string) {
+    this.updateAndReplicate({
+      referral: { referrerId, referredGameId: refferredGameId },
+    });
+  }
+
+  setEmbedId(embedId: string) {
+    this.updateAndReplicate({
+      embedId,
+    });
+  }
+
+  setDistributorKeys(distributorKeys: Record<string, string>) {
+    this.updateAndReplicate({
+      distributorKeys,
+    });
+  }
+
+  setContext(context: Context | undefined) {
+    this.updateAndReplicate({
+      context,
+    });
+  }
+
+  /** UI Methods */
+
+  showPoints() {
+    if (this.state.ui?.usePointsWidget) {
+      return;
+    }
+    this.updateAndReplicate({
+      pointsDisplay: {
+        ...this.state.pointsDisplay,
+        show: true,
+      },
+    });
+    this.widget?.show({
+      maxHeight: 'auto',
+      height: 'auto',
+    });
+  }
+
+  hidePoints() {
+    this.updateAndReplicate({
+      pointsDisplay: {
+        ...this.state.pointsDisplay,
+        show: false,
+      },
+    });
+    this.widget?.hide();
+  }
+
+  setTheme(theme: Theme) {
+    this.widget?.setTheme(theme);
+  }
+
+  /** Internal Methods */
+
+  private _checkReady() {
+    if (!this.state.isReady) {
+      throw new Error('SDK not initialized. Call init() before using the SDK.');
+    }
+  }
+
+  private async fetch<T>(endpoint: string, options?: RequestInit, authed: boolean = false) {
+    let bearerToken: string | undefined;
+    if (authed) {
+      const { token, updatedAt } = this.state.session ?? {};
+
+      if (!token || (updatedAt ?? 0) + 1000 * 60 * 30 < Date.now()) {
+        const gameId = this.state.gameId;
+        const apiKey = this.state.apiKey;
+        if (!apiKey) {
+          throw new Error(
+            'No API key found. Please pass an API key to the SDK constructor or include an ogp-key meta tag in your HTML.',
+          );
+        }
+        if (!gameId) {
+          throw new Error('No Game ID found. Failed to fetch session token.');
+        }
+
+        // Get fresh Privy token from widget if needed
+        if (!this.state.privyAccessToken && this._widget) {
+          console.info('[OpenGameSDK] Requesting fresh Privy token from widget');
+          await this.requestPrivyToken();
+        }
+        if (!this.state.privyAccessToken) {
+          throw new Error('No Privy access token found. User must be authenticated.');
+        }
+
+        console.info('[OpenGameSDK] Updating session token for game:', gameId);
+        const token = await this.getSessionToken(apiKey, gameId);
+        this.updateAndReplicate({
+          session: {
+            token,
+            updatedAt: Date.now(),
+          },
+        });
+        bearerToken = `Bearer ${token}`;
+      } else {
+        bearerToken = `Bearer ${token}`;
+      }
+    }
+
+    const isFormData = options?.body instanceof FormData;
+
+    const headers = {
+      ...(!isFormData && { 'Content-Type': 'application/json' }),
+      ...(bearerToken && { Authorization: bearerToken }),
+      ...options?.headers,
+    };
+
+    return await this.api.fetch<T>(`${endpoint}`, {
+      ...options,
+      headers,
+    });
+  }
+
+  private async paginatedFetch<T>(
+    endpoint: string,
+    opts: PaginatedFetchOpts,
+    reqOptions?: RequestInit,
+    authed: boolean = false,
+  ) {
+    let bearerToken: string | undefined;
+    if (authed) {
+      const { token, updatedAt } = this.state.session ?? {};
+
+      if (!token || (updatedAt ?? 0) + 1000 * 60 * 30 < Date.now()) {
+        const gameId = this.state.gameId;
+        const apiKey = this.state.apiKey;
+        if (!apiKey) {
+          throw new Error(
+            'No API key found. Please pass an API key to the SDK constructor or include an ogp-key meta tag in your HTML.',
+          );
+        }
+        if (!gameId) {
+          throw new Error('No Game ID found. Failed to fetch session token.');
+        }
+
+        // Get fresh Privy token from widget if needed
+        if (!this.state.privyAccessToken && this._widget) {
+          console.info('[OpenGameSDK] Requesting fresh Privy token from widget');
+          await this.requestPrivyToken();
+        }
+        if (!this.state.privyAccessToken) {
+          throw new Error('No Privy access token found. User must be authenticated.');
+        }
+
+        console.info('[OpenGameSDK] Updating session token for game:', gameId);
+        const token = await this.getSessionToken(apiKey, gameId);
+        this.state.session = { token, updatedAt: Date.now() };
+        bearerToken = `Bearer ${token}`;
+      } else {
+        bearerToken = `Bearer ${token}`;
+      }
+    }
+
+    const headers = {
+      ...(bearerToken && { Authorization: bearerToken }),
+      ...reqOptions?.headers,
+    };
+
+    const { limit = 50, cursor, sort, sortBy, query } = opts;
+    const searchParams = new URLSearchParams({
+      limit: limit.toString(),
+    });
+    if (cursor) {
+      searchParams.append('cursor', cursor);
+    }
+    if (sort && sort !== '') {
+      searchParams.append('sort', sort);
+    }
+    if (sortBy && sortBy !== '') {
+      searchParams.append('sortBy', sortBy);
+    }
+    if (query && query !== '') {
+      searchParams.append('query', query);
+    }
+    return await this.api.paginatedFetch<T>(`${endpoint}?${searchParams.toString()}`, {
+      ...reqOptions,
+      headers,
+    });
+  }
+
+  private _setupCarouselBridge() {
+    window.addEventListener('message', (event) => {
+      const isValidOrigin = event.origin === config.carouselURL;
+      if (isValidOrigin) {
+        handleCarouselMessages(this, event.data);
+      }
+    });
+    console.log('Sending Ready Message to Carousel');
+    this._sendMessageToCarousel({
+      action: SDKActions.SDKReady,
+      data: {
+        apiKey: this.state.apiKey,
+        gameId: this.state.gameId ?? '',
+        playerId: this.state.playerId ?? '',
+      },
+    });
+  }
+
+  private _deriveApiKey() {
+    const apiKey = document.querySelector('meta[name="x-ogp-key"]')?.getAttribute('content');
+    if (!apiKey) {
+      throw new Error(
+        'No API key found. Please pass an API key to the SDK constructor or include an ogp-key meta tag in your HTML.',
+      );
+    }
+    return apiKey;
+  }
+
+  private _deriveGameId() {
+    const params = new URLSearchParams(window.location.search);
+    const gameId = params.get('gameId');
+    if (!gameId) {
+      return undefined;
+    }
+    return gameId;
+  }
+
+  private _setupDashboardBridge() {
+    window.addEventListener('message', async (event) => {
+      // Only process dashboard messages
+      const dashboardOrigin = new URL(config.dashboardURL).origin;
+      const eventOriginHostname = new URL(event.origin).hostname;
+
+      const isValidOrigin =
+        event.origin === dashboardOrigin ||
+        eventOriginHostname === 'play.fun' ||
+        eventOriginHostname.endsWith('.play.fun') ||
+        isDevOrigin(eventOriginHostname);
+
+      // Debug logging for message origin validation
+      if (
+        event.data?.action &&
+        (event.data.action === DashboardActions.ReplicateAuth ||
+          event.data.action === DashboardActions.Logout)
+      ) {
+        console.log(
+          '[OpenGameSDK] Received dashboard message:',
+          event.data.action,
+          'from origin:',
+          event.origin,
+          'expected:',
+          dashboardOrigin,
+          'valid:',
+          isValidOrigin,
+        );
+      }
+
+      if (!isValidOrigin) {
+        return;
+      }
+
+      const msg = event.data as DashboardMessages;
+      if (!msg.action) {
+        return;
+      }
+
+      switch (msg.action) {
+        case DashboardActions.SetReferral:
+          console.log('[OpenGameSDK] Received SetReferral from dashboard:', msg.data);
+          this.setReferrer(msg.data.referrerId, msg.data.referredGameId);
+          return;
+        case DashboardActions.SetDistributor:
+          console.log('[OpenGameSDK] Received SetDistributor from dashboard:', msg.data);
+          this.setDistributorKeys(msg.data.distributorKeys);
+          return;
+        case DashboardActions.RefreshMultiplier:
+          console.log('[OpenGameSDK] Received RefreshMultiplier from dashboard:', msg.data);
+          const { points: refreshedPoints, activeMultiplier: refreshedActivedMultiplier } =
+            await this.getPoints();
+          this.updateAndReplicate({
+            pointsDisplay: {
+              ...this.state.pointsDisplay,
+              points: parseInt(refreshedPoints),
+              activeMultiplier: refreshedActivedMultiplier,
+            },
+          });
+          return;
+        case DashboardActions.Logout:
+          console.log('[OpenGameSDK] Received Logout event');
+          this.updateAndReplicate({
+            playerId: undefined,
+            session: undefined,
+            pointsDisplay: {
+              ...this.state.pointsDisplay,
+              points: 0,
+            },
+            sessionPoints: undefined,
+            identityToken: undefined,
+          });
+          break;
+        case DashboardActions.ReplicateAuth:
+          console.log('[OpenGameSDK] Received ReplicateAuth:', msg.data);
+
+          const authData: ReplicateAuthData = {
+            gameId: msg.data.gameId,
+            playerId: msg.data.playerId,
+            identityToken: msg.data.identityToken,
+            privyAccessToken: msg.data.privyAccessToken,
+          };
+
+          // If we're currently initializing, resolve the promise if waiting or store for later
+          if (this._isInitializing) {
+            console.log('[OpenGameSDK] Init in progress, storing auth for init to use');
+            if (this._replicateAuthResolver) {
+              // Init is waiting for this data
+              this._replicateAuthResolver(authData);
+              this._replicateAuthResolver = null;
+            } else {
+              // Store for init to pick up
+              this._pendingReplicateAuth = authData;
+            }
+            return;
+          }
+
+          // If init hasn't started yet, store the data for init to use
+          if (!this.state.isReady) {
+            console.log('[OpenGameSDK] Init not started, storing auth for init to use');
+            this._pendingReplicateAuth = authData;
+            return;
+          }
+
+          // Init is complete, safe to call loadGame
+          console.log(`[OpenGameSDK:${this._instanceId}] Init complete loading info`, {
+            playerId: authData.playerId,
+            hasPendingCallback: !!this._pendingLoginCallback,
+          });
+
+          // Skip if no playerId - user is not logged in
+          if (!authData.playerId) {
+            console.log(
+              `[OpenGameSDK:${this._instanceId}] No playerId in ReplicateAuth, skipping session setup`,
+            );
+            return;
+          }
+
+          // Set Privy access token first so getSessionToken can use it for auth
+          this.state.privyAccessToken = authData.privyAccessToken;
+          this.state.identityToken = authData.identityToken;
+
+          const token = await this.getSessionToken(this.state.apiKey, authData.gameId);
+          // playerId is now set by getSessionToken from server response
+          const { points, activeMultiplier } = await this.getPoints();
+          this.updateAndReplicate({
+            identityToken: authData.identityToken,
+            privyAccessToken: authData.privyAccessToken,
+            session: { token, updatedAt: Date.now() },
+            pointsDisplay: {
+              ...this.state.pointsDisplay,
+              points: parseInt(points),
+              activeMultiplier,
+            },
+          });
+
+          console.log(
+            `[OpenGameSDK:${this._instanceId}] Session updated, checking pending callback:`,
+            !!this._pendingLoginCallback,
+          );
+
+          // Emit OnLoginSuccess so games know login completed (important for dashboard mode)
+          // Note: SDKEvents.OnLoginSuccess = 'LoginSuccess', but games may listen for 'OnLoginSuccess'
+          // So we emit both to ensure compatibility
+          console.log(`[OpenGameSDK:${this._instanceId}] Emitting OnLoginSuccess event`);
+          this.emit(SDKEvents.OnLoginSuccess);
+          this.emit('OnLoginSuccess' as SDKEvents);
+
+          if (this._pendingLoginCallback) {
+            console.log(`[OpenGameSDK:${this._instanceId}] Calling pending login callback`);
+            this._pendingLoginCallback();
+            this._pendingLoginCallback = null;
+          }
+      }
+    });
+    // Note: Don't send SDKReady from constructor - it's sent from init() when in dashboard mode
+    // This ensures the SDK is actually ready to receive ReplicateAuth when it signals readiness
+  }
+
+  private _sendMessageToCarousel(msg: SDKMessages) {
+    window.parent.postMessage(msg, '*');
+  }
+
+  private _sendReadyToDashboard() {
+    // Send SDKReady to dashboard so it can respond with ReplicateAuth
+    window.parent.postMessage(
+      {
+        action: SDKActions.SDKReady,
+        data: {
+          apiKey: this.state.apiKey,
+          gameId: this.state.gameId ?? '',
+          playerId: this.state.playerId ?? '',
+        },
+      },
+      '*',
+    );
+  }
+
+  private getWidgetUrl() {
+    // Use state.isDashboard which includes auto-detected dashboard mode
+    const baseWidgetUrl = config.widgetURL;
+
+    const url = new URL(baseWidgetUrl);
+    const queryParams = new URLSearchParams(url.search);
+    if (this.opts.logLevel) {
+      queryParams.append('logLevel', this.opts.logLevel.toString());
+    }
+    if (this.state.isEmbedSession) {
+      queryParams.append('inCarousel', 'true');
+    }
+    if (this.state.isDashboard) {
+      queryParams.append('inDashboard', 'true');
+    }
+    url.search = queryParams.toString();
+    return url.toString();
+  }
+
+  private async getSessionToken(apiKey: string, gameId: string) {
+    const params = new URLSearchParams({
+      apiKey,
+      gameId,
+    });
+
+    // Include Privy access token for authentication
+    // Server will use the authenticated user's Privy ID as the canonical playerId
+    const headers: Record<string, string> = {};
+    if (this.state.privyAccessToken) {
+      headers['Authorization'] = `Bearer ${this.state.privyAccessToken}`;
+    }
+
+    const res = await this.api.fetch<{ token: string; playerId: string }>(
+      `/play/session-token?${params.toString()}`,
+      {
+        method: 'GET',
+        headers,
+      },
+    );
+    if (!res) {
+      throw new Error('Failed to fetch session token');
+    }
+
+    // Update state with canonical playerId from server
+    // This ensures proof computation uses the same ID the server expects
+    this.state.playerId = res.playerId;
+
+    return res.token;
+  }
+
+  /**
+   * Request a fresh Privy access token from the widget.
+   * The widget will respond with SetPrivyToken containing a fresh token.
+   */
+  private async requestPrivyToken(): Promise<string> {
+    if (!this._widget) {
+      throw new Error('No widget available to request Privy token');
+    }
+
+    const requestId = generateUUID();
+
+    return new Promise((resolve, reject) => {
+      // Set up timeout
+      const timeout = setTimeout(() => {
+        this._privyTokenResolvers.delete(requestId);
+        reject(new Error('Privy token request timed out'));
+      }, 10000);
+
+      // Store resolver
+      this._privyTokenResolvers.set(requestId, (token: string) => {
+        clearTimeout(timeout);
+        this._privyTokenResolvers.delete(requestId);
+        resolve(token);
+      });
+
+      // Send request to widget
+      this._widget!.sendMessage({
+        action: SDKActions.RequestPrivyToken,
+        data: { requestId },
+      });
+    });
+  }
+
+  /**
+   * Handle Privy token response from widget.
+   * Called by widget message handler.
+   */
+  handlePrivyTokenResponse(token: string, requestId: string) {
+    const resolver = this._privyTokenResolvers.get(requestId);
+    if (resolver) {
+      this.state.privyAccessToken = token;
+      resolver(token);
+    } else {
+      console.warn('[OpenGameSDK] Received Privy token for unknown request:', requestId);
+    }
+  }
+
+  /** Getters and Setters */
+  get widget() {
+    return this._widget;
+  }
+
+  set widget(value: WidgetBridge | null) {
+    this._widget = value;
+  }
+
+  get pointsDisplay() {
+    return this.state.pointsDisplay;
+  }
+
+  get ui() {
+    return this.state.ui;
+  }
+
+  get gameId() {
+    return this.state.gameId;
+  }
+
+  get playerId() {
+    return this.state.playerId;
+  }
+
+  get sessionPoints() {
+    return this.state.sessionPoints ? decodePointsObf(this.state.sessionPoints) : 0;
+  }
+
+  get activeMultiplier() {
+    return this.state.pointsDisplay?.activeMultiplier ?? 1;
+  }
+
+  get widgetUrl() {
+    return this.getWidgetUrl();
+  }
+
+  get embedId() {
+    return this.state.embedId;
+  }
+
+  get hasSession() {
+    return (
+      !!this.state.session?.token &&
+      !!this.state.session?.updatedAt &&
+      this.state.session.updatedAt > Date.now() - 1000 * 60 * 30
+    );
+  }
+
+  get isDashboard() {
+    return this.state.isDashboard;
+  }
+
+  set isDashboard(value: boolean | undefined) {
+    this.updateAndReplicate({
+      isDashboard: value,
+    });
+  }
+
+  set playerId(value: string | undefined) {
+    // playerId is now determined by server based on Privy auth
+    // This setter is kept for backward compatibility but doesn't fetch session token
+    // Use the authentication flow to set playerId properly
+    if (!value) {
+      this.updateAndReplicate({ playerId: value, session: undefined });
+    } else {
+      console.warn(
+        '[OpenGameSDK] Setting playerId directly is deprecated. playerId is now determined by Privy authentication.',
+      );
+      this.updateAndReplicate({ playerId: value });
+    }
+  }
+
+  private updateAndReplicate(state: RecursivePartial<SDKState>) {
+    const oldState = this.state;
+    const newState = {
+      ...oldState,
+      ...state,
+    } as SDKState;
+
+    this.state = newState;
+
+    console.log('[OpenGameSDK] Replication State:', newState);
+
+    this.widget?.sendMessage({
+      action: SDKActions.Replicate,
+      data: newState,
+    });
+  }
+}