@looplay/sdk 0.2.1 → 0.5.0

package/README.md

@@ -41,6 +41,51 @@ looplayAuth.subscribe((state) => { /* re-render when auth arrives/clears */ });
 await looplayAuth.trackPlay(playTimeSeconds);
 await looplayAuth.trackMatch(matchId, { durationSeconds, isWin: true });
 await looplayAuth.emitGameEvent('CUSTOM_ACTION', { value: 1 });
+await looplayAuth.requestAds();
+```
+
+### Rewarded ads via parent window
+
+When the game runs inside an iframe, you can ask the parent page to open a
+rewarded ad by sending `LOOPLAY_REQUEST_ADS`. This is the right pattern for a
+Telegram Mini App shell: the game stays inside the iframe, and the parent page
+owns the Adsgram integration. The parent should bridge that message to Adsgram
+(or any other rewarded-ad SDK) and then reply with `LOOPLAY_ADS_WATCHED` using
+the same `requestId` after the ad finishes.
+
+If there is no ad available, the parent should reply with
+`LOOPLAY_ADS_UNAVAILABLE` for the same `requestId`. The SDK will resolve the
+request as `false` and continue normally.
+
+If the parent never answers, `requestAds()` times out after 5 seconds by
+default and resolves `false`.
+
+```ts
+window.addEventListener('message', async (event) => {
+  const data = event.data;
+  if (!data || data.type !== 'LOOPLAY_REQUEST_ADS') return;
+
+  try {
+    // Replace this with your Adsgram integration.
+    await showRewardedAd(data.gameId);
+
+    event.source?.postMessage(
+      {
+        type: 'LOOPLAY_ADS_WATCHED',
+        requestId: data.requestId,
+      },
+      event.origin
+    );
+  } catch {
+    event.source?.postMessage(
+      {
+        type: 'LOOPLAY_ADS_UNAVAILABLE',
+        requestId: data.requestId,
+      },
+      event.origin
+    );
+  }
+});
 ```
 
 ### Drop-in `<script>` tag (no build step required)
@@ -85,4 +130,4 @@ session (including the refresh token) in `localStorage`, which is convenient
 but readable by any script on the page (XSS exposure). Prefer it only for
 games where that tradeoff is acceptable; for higher-security needs, keep the
 default in-memory storage or implement an `AuthStorage` backed by a more
-restrictive mechanism.
+restrictive mechanism.

package/dist/looplay-sdk.cjs.js

@@ -249,107 +249,141 @@ var ServiceClient = class {
   // Games
   // ─────────────────────────────────────────────────────────────────────────────
   async listGames(query) {
-    return this.http.request("GET", "/games", { query });
+    return this.http.request("GET", "/sdk/games", { query });
   }
   async getGameDetail(gameId, bearerToken) {
-    return this.http.request("GET", `/games/${encodeURIComponent(gameId)}`, {
+    return this.http.request("GET", `/sdk/games/${encodeURIComponent(gameId)}`, {
       bearerToken
     });
   }
   async listRecentPlayed(bearerToken, query) {
-    return this.http.request("GET", "/games/recent-play", { bearerToken, query });
+    return this.http.request("GET", "/sdk/games/recent-play", { bearerToken, query });
   }
-  async trackPlay(auth, gameId, playTimeSeconds) {
-    const body = { playTimeSeconds };
-    await this.http.request("POST", `/games/${encodeURIComponent(gameId)}/play`, {
+  async trackView(auth, gameId) {
+    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/view`, {
       ...auth,
+      headers: this.trackingHeaders(auth)
+    });
+    return true;
+  }
+  async trackPlay(auth, gameId, attemptId, playTimeSeconds) {
+    const body = { playTimeSeconds, attemptId };
+    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/play`, {
+      ...auth,
+      headers: this.trackingHeaders(auth),
       body
     });
     return true;
   }
   async trackMatchEnd(auth, gameId, body) {
-    await this.http.request("POST", `/games/${encodeURIComponent(gameId)}/end`, {
+    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/end`, {
       ...auth,
+      headers: this.trackingHeaders(auth),
       body
     });
     return true;
   }
   async emitGameEvent(auth, gameId, body) {
-    return this.http.request("POST", `/games/${encodeURIComponent(gameId)}/emit`, {
+    return this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/emit`, {
       ...auth,
+      headers: this.trackingHeaders(auth),
       body
     });
   }
+  /**
+   * Anonymous runtimes must call this before any tracking call; logged-in
+   * runtimes should still call it to get a `trackingSessionId` for unified
+   * tracing — see `GameTrackingSessionDto`.
+   */
+  async issueTrackingSession(anonId) {
+    return this.http.request("POST", "/sdk/games/tracking/bootstrap", {
+      headers: { "x-looplay-anon-id": anonId }
+    });
+  }
+  trackingHeaders(auth) {
+    return {
+      "x-game-tracking-session-id": auth.trackingSessionId,
+      "x-looplay-anon-token": auth.anonTrackingToken
+    };
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Game assets — spend coin balance on assets defined by the game's
+  // creator. Coin balance itself comes from getBalances()/getMyBalance().
+  // ─────────────────────────────────────────────────────────────────────────────
+  async listGameAssets(gameId, bearerToken) {
+    return this.http.request("GET", `/sdk/games/${encodeURIComponent(gameId)}/assets`, {
+      bearerToken
+    });
+  }
+  async purchaseGameAsset(bearerToken, gameId, assetCode, body = {}) {
+    return this.http.request(
+      "POST",
+      `/sdk/games/${encodeURIComponent(gameId)}/assets/${encodeURIComponent(assetCode)}/purchase`,
+      { bearerToken, body }
+    );
+  }
   // ─────────────────────────────────────────────────────────────────────────────
   // Balance
   // ─────────────────────────────────────────────────────────────────────────────
   async getBalances(bearerToken, query) {
-    return this.http.request("GET", "/balance", { bearerToken, query });
+    return this.http.request("GET", "/sdk/balance", { bearerToken, query });
   }
   async getBalanceHistory(bearerToken, query) {
-    return this.http.request("GET", "/balance/history", { bearerToken, query });
+    return this.http.request("GET", "/sdk/balance/history", { bearerToken, query });
   }
   // ─────────────────────────────────────────────────────────────────────────────
   // User
   // ─────────────────────────────────────────────────────────────────────────────
   async getMyProfile(bearerToken) {
-    return this.http.request("GET", "/user/profile", { bearerToken });
+    return this.http.request("GET", "/sdk/user/profile", { bearerToken });
   }
   async getMyBalance(bearerToken) {
-    return this.http.request("GET", "/user/balance", { bearerToken });
+    return this.http.request("GET", "/sdk/user/balance", { bearerToken });
   }
   // ─────────────────────────────────────────────────────────────────────────────
   // Referrals
   // ─────────────────────────────────────────────────────────────────────────────
   async listReferrals(bearerToken, query) {
-    return this.http.request("GET", "/referrals", { bearerToken, query });
+    return this.http.request("GET", "/sdk/referrals", { bearerToken, query });
   }
   async setReferral(bearerToken, body) {
-    return this.http.request("POST", "/referrals/set", { bearerToken, body });
+    return this.http.request("POST", "/sdk/referrals/set", { bearerToken, body });
   }
   // ─────────────────────────────────────────────────────────────────────────────
-  // Tasks / Quests
+  // Tasks
   // ─────────────────────────────────────────────────────────────────────────────
   async listTasks(bearerToken) {
-    return this.http.request("GET", "/task", { bearerToken });
+    return this.http.request("GET", "/sdk/task", { bearerToken });
   }
   async listFinishedTasks(bearerToken) {
-    return this.http.request("GET", "/task/finished", { bearerToken });
+    return this.http.request("GET", "/sdk/task/finished", { bearerToken });
   }
   async startTask(bearerToken, body) {
-    return this.http.request("POST", "/task/start", { bearerToken, body });
+    return this.http.request("POST", "/sdk/task/start", { bearerToken, body });
   }
   async claimTask(bearerToken, body) {
-    return this.http.request("POST", "/task/claim", { bearerToken, body });
-  }
-  async getPlatformQuests(bearerToken, query) {
-    return this.http.request("GET", "/quest/platform", { bearerToken, query });
-  }
-  async getCampaignQuests(bearerToken, query) {
-    return this.http.request("GET", "/quest/campaign", { bearerToken, query });
-  }
-  async claimQuest(bearerToken, questProgressId) {
-    return this.http.request("POST", `/quest/${encodeURIComponent(questProgressId)}/claim`, {
-      bearerToken
-    });
-  }
-  async claimMilestone(bearerToken, milestoneId, body) {
-    return this.http.request(
-      "POST",
-      `/quest/milestone/${encodeURIComponent(milestoneId)}/claim`,
-      {
-        bearerToken,
-        body
-      }
-    );
+    return this.http.request("POST", "/sdk/task/claim", { bearerToken, body });
   }
 };
 
 // src/apps/api-client.ts
+function generateId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
 var ApiClient = class {
   raw;
   getAccessToken;
   getAnonymousId;
+  trackingSession;
+  trackingSessionPromise;
+  currentAttemptId;
   constructor(options) {
     if (!options.baseUrl) throw new MissingBaseUrlError();
     this.raw = new ServiceClient({
@@ -377,14 +411,46 @@ var ApiClient = class {
   /**
    * Resolves auth for the tracking endpoints: a real bearer token if logged
    * in, otherwise an anonymous device id. Throws only when neither is
-   * available — anonymous tracking still requires *some* identity.
+   * available — anonymous tracking still requires *some* identity. Also
+   * attaches a `trackingSessionId`/`anonTrackingToken` (bootstrapped and
+   * cached lazily) — the backend's tracking contract expects these even for
+   * logged-in callers, for unified tracing.
    */
   async resolveTrackingAuth() {
     const bearerToken = await this.getAccessToken?.();
-    if (bearerToken) return { bearerToken };
-    const anonId = this.getAnonymousId?.();
-    if (anonId) return { anonId };
-    throw new NotAuthenticatedError();
+    const anonId = bearerToken ? void 0 : this.getAnonymousId?.();
+    if (!bearerToken && !anonId) throw new NotAuthenticatedError();
+    const session = await this.ensureTrackingSession(anonId);
+    return {
+      bearerToken,
+      anonId,
+      trackingSessionId: session?.trackingSessionId,
+      anonTrackingToken: session?.anonTrackingToken
+    };
+  }
+  /**
+   * Bootstraps (and caches until near expiry) the platform tracking
+   * session. Swallows failures — tracking calls still work without it,
+   * just without unified session tracing.
+   */
+  async ensureTrackingSession(anonId) {
+    const now = Date.now();
+    if (this.trackingSession && this.trackingSession.expiresAtMs > now + 3e4) {
+      return this.trackingSession;
+    }
+    if (!this.trackingSessionPromise) {
+      this.trackingSessionPromise = this.raw.issueTrackingSession(anonId).then((dto) => {
+        this.trackingSession = {
+          trackingSessionId: dto.trackingSessionId,
+          anonTrackingToken: dto.trackingToken,
+          expiresAtMs: new Date(dto.expiresAt).getTime()
+        };
+        return this.trackingSession;
+      }).catch(() => void 0).finally(() => {
+        this.trackingSessionPromise = void 0;
+      });
+    }
+    return this.trackingSessionPromise;
   }
   async getGameDetail(gameId) {
     const token = await this.getAccessToken?.();
@@ -394,9 +460,24 @@ var ApiClient = class {
     const token = await this.requireToken();
     return this.raw.listRecentPlayed(token, query);
   }
+  /** Call once when the game view opens, before any play/match tracking. */
+  async trackView(gameId) {
+    const auth = await this.resolveTrackingAuth();
+    return this.raw.trackView(auth, gameId);
+  }
+  /**
+   * Starts a new play attempt and returns its id. Call when the user
+   * presses Play; `trackPlay` reuses this id across calls until the next
+   * `startAttempt()`, auto-starting one on first use if none was started.
+   */
+  startAttempt() {
+    this.currentAttemptId = generateId();
+    return this.currentAttemptId;
+  }
   async trackPlay(gameId, playTimeSeconds) {
     const auth = await this.resolveTrackingAuth();
-    return this.raw.trackPlay(auth, gameId, playTimeSeconds);
+    const attemptId = this.currentAttemptId ?? this.startAttempt();
+    return this.raw.trackPlay(auth, gameId, attemptId, playTimeSeconds);
   }
   async trackMatch(gameId, body) {
     const auth = await this.resolveTrackingAuth();
@@ -412,6 +493,16 @@ var ApiClient = class {
     };
     return this.raw.emitGameEvent(auth, gameId, body);
   }
+  /** Lists assets purchasable in `gameId`, defined by that game's creator. */
+  async listGameAssets(gameId) {
+    const token = await this.getAccessToken?.();
+    return this.raw.listGameAssets(gameId, token);
+  }
+  /** Spends coin balance to purchase an asset — see PurchaseGameAssetRequest for dedupe/quantity. */
+  async purchaseGameAsset(gameId, assetCode, opts) {
+    const token = await this.requireToken();
+    return this.raw.purchaseGameAsset(token, gameId, assetCode, opts);
+  }
   async getMyProfile() {
     const token = await this.requireToken();
     return this.raw.getMyProfile(token);
@@ -452,22 +543,6 @@ var ApiClient = class {
     const token = await this.requireToken();
     return this.raw.claimTask(token, body);
   }
-  async getPlatformQuests(query) {
-    const token = await this.requireToken();
-    return this.raw.getPlatformQuests(token, query);
-  }
-  async getCampaignQuests(query) {
-    const token = await this.requireToken();
-    return this.raw.getCampaignQuests(token, query);
-  }
-  async claimQuest(questProgressId) {
-    const token = await this.requireToken();
-    return this.raw.claimQuest(token, questProgressId);
-  }
-  async claimMilestone(milestoneId, body) {
-    const token = await this.requireToken();
-    return this.raw.claimMilestone(token, milestoneId, body);
-  }
 };
 
 // src/looplay-sdk.ts
@@ -507,6 +582,19 @@ var LooplaySDK = class {
     if (!this.api) throw new MissingBaseUrlError();
     return this.api.getMyProfile();
   }
+  /** Call once when the game view opens, before any play/match tracking. */
+  async trackView() {
+    this.assertInitialized();
+    if (!this.api) throw new MissingBaseUrlError();
+    if (!this.gameId) throw new NotInitializedError();
+    return this.api.trackView(this.gameId);
+  }
+  /** Starts a new play attempt; call when the user presses Play. Returns the attempt id. */
+  startAttempt() {
+    this.assertInitialized();
+    if (!this.api) throw new MissingBaseUrlError();
+    return this.api.startAttempt();
+  }
   async trackPlay(playTimeSeconds) {
     this.assertInitialized();
     if (!this.api) throw new MissingBaseUrlError();
@@ -652,6 +740,7 @@ var TelegramAuthProvider = class {
 // src/iframe/iframe-auth.ts
 var DEFAULT_ANON_ID_STORAGE_KEY = "looplay:anon-id";
 var DEFAULT_ANONYMOUS_FALLBACK_TIMEOUT_MS = 4e3;
+var DEFAULT_REQUEST_ADS_TIMEOUT_MS = 5e3;
 var INITIAL_STATE = {
   jwt: null,
   gameId: null,
@@ -701,6 +790,12 @@ var LooplayIframeAuth = class {
   options;
   messageListener = null;
   anonymousFallbackTimer = null;
+  pendingAdsRequests = /* @__PURE__ */ new Map();
+  requestAdsSequence = 0;
+  adsRequestInFlight = false;
+  adsRequestsSent = 0;
+  lastAdsRequestAt = 0;
+  autoAdsActionCount = 0;
   constructor(options = {}) {
     this.options = options;
   }
@@ -735,8 +830,57 @@ var LooplayIframeAuth = class {
       this.debug("standalone mode detected; auth request skipped");
       return;
     }
-    this.debug("requesting auth from parent", { targetOrigin: this.resolveParentOrigin() ?? "*" });
-    window.parent.postMessage({ type: "LOOPLAY_AUTH_REQUEST" }, this.resolveParentOrigin() ?? "*");
+    this.debug("requesting auth from parent", {
+      targetOrigin: this.resolveParentOrigin() ?? "*"
+    });
+    window.parent.postMessage(
+      { type: "LOOPLAY_AUTH_REQUEST" },
+      this.resolveParentOrigin() ?? "*"
+    );
+  }
+  /**
+   * Requests the parent host to show a rewarded ad.
+   * In a Telegram Mini App setup, the game sends this request from the iframe
+   * and the parent page (the Mini App shell) bridges it to Adsgram, then
+   * responds with `LOOPLAY_ADS_WATCHED` after the ad finishes.
+   */
+  requestAds(options = {}) {
+    if (typeof window === "undefined" || window.parent === window) {
+      this.debug("requestAds skipped; standalone mode detected");
+      return Promise.resolve(false);
+    }
+    if (this.adsRequestInFlight) {
+      this.debug("requestAds skipped; another ad request is already in flight");
+      return Promise.resolve(false);
+    }
+    const parentOrigin = this.resolveParentOrigin() ?? "*";
+    const requestId = `ads-${Date.now()}-${++this.requestAdsSequence}`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_ADS_TIMEOUT_MS;
+    this.adsRequestInFlight = true;
+    this.adsRequestsSent += 1;
+    this.lastAdsRequestAt = Date.now();
+    this.debug("requesting rewarded ad from parent", {
+      requestId,
+      targetOrigin: parentOrigin,
+      gameId: this.getGameId()
+    });
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingAdsRequests.delete(requestId);
+        this.adsRequestInFlight = false;
+        this.debug("requestAds timed out", { requestId, timeoutMs });
+        resolve(false);
+      }, timeoutMs);
+      this.pendingAdsRequests.set(requestId, { resolve, timer });
+      window.parent.postMessage(
+        {
+          type: "LOOPLAY_REQUEST_ADS",
+          requestId,
+          gameId: this.getGameId()
+        },
+        parentOrigin
+      );
+    });
   }
   /** Idempotent; attaches the postMessage listener (if embedded) and arms the anonymous fallback. */
   init() {
@@ -760,14 +904,13 @@ var LooplayIframeAuth = class {
     this.messageListener = (event) => {
       if (event.source !== window.parent) return;
       if (parentOrigin && event.origin !== parentOrigin) {
-        this.debug("ignored auth message from unexpected origin", {
+        this.debug("ignored message from unexpected origin", {
           expectedOrigin: parentOrigin,
           receivedOrigin: event.origin
         });
         return;
       }
-      if (!isRecord(event.data) || event.data.type !== "LOOPLAY_AUTH") return;
-      this.handleAuthMessage(event.data, event.origin);
+      this.handleIncomingMessage(event.data, event.origin);
     };
     window.addEventListener("message", this.messageListener);
     this.anonymousFallbackTimer = setTimeout(() => {
@@ -784,6 +927,11 @@ var LooplayIframeAuth = class {
     if (this.anonymousFallbackTimer !== null) {
       clearTimeout(this.anonymousFallbackTimer);
     }
+    for (const pending of this.pendingAdsRequests.values()) {
+      if (pending.timer !== null) clearTimeout(pending.timer);
+      pending.resolve(false);
+    }
+    this.pendingAdsRequests.clear();
     this.messageListener = null;
     this.anonymousFallbackTimer = null;
     this.initialized = false;
@@ -802,14 +950,36 @@ var LooplayIframeAuth = class {
     });
     return this.client;
   }
+  /** Call once when the game view opens, before any play/match tracking. */
+  trackView() {
+    const gameId = this.getGameId();
+    if (!this.canTrack() || !gameId) {
+      this.debug("trackView skipped; auth is not ready", {
+        hasGameId: Boolean(gameId)
+      });
+      return Promise.resolve(false);
+    }
+    this.debug("trackView dispatched", { gameId });
+    return this.getClient().trackView(gameId);
+  }
+  /** Starts a new play attempt; call when the user presses Play. Returns the attempt id. */
+  startAttempt() {
+    return this.getClient().startAttempt();
+  }
   trackPlay(playTimeSeconds) {
     const gameId = this.getGameId();
     if (!this.canTrack() || !gameId) {
-      this.debug("trackPlay skipped; auth is not ready", { hasGameId: Boolean(gameId) });
+      this.debug("trackPlay skipped; auth is not ready", {
+        hasGameId: Boolean(gameId)
+      });
       return Promise.resolve(false);
     }
     this.debug("trackPlay dispatched", { gameId, playTimeSeconds });
-    return this.getClient().trackPlay(gameId, playTimeSeconds);
+    const result = this.getClient().trackPlay(gameId, playTimeSeconds);
+    void result.then((ok) => {
+      if (ok) this.recordAutoRequestAdsActivity();
+    }).catch(() => void 0);
+    return result;
   }
   trackMatch(matchId, opts) {
     const gameId = this.getGameId();
@@ -818,12 +988,16 @@ var LooplayIframeAuth = class {
       return Promise.resolve(false);
     }
     this.debug("trackMatch dispatched", { gameId, matchId, ...opts });
-    return this.getClient().trackMatch(gameId, {
+    const result = this.getClient().trackMatch(gameId, {
       matchId,
       matchDurationSeconds: opts.durationSeconds,
       isCompleted: opts.isCompleted,
       isWin: opts.isWin
     });
+    void result.then((ok) => {
+      if (ok) this.recordAutoRequestAdsActivity();
+    }).catch(() => void 0);
+    return result;
   }
   emitGameEvent(actionCode, opts) {
     const gameId = this.getGameId();
@@ -836,7 +1010,8 @@ var LooplayIframeAuth = class {
   }
   /** Idempotent; auto-emits GAME_STARTED exactly once per distinct auth session (bearer or anonymous). */
   initLifecycleTracking() {
-    if (this.lifecycleTrackingInitialized || typeof window === "undefined") return;
+    if (this.lifecycleTrackingInitialized || typeof window === "undefined")
+      return;
     this.lifecycleTrackingInitialized = true;
     this.debug("lifecycle tracking initialized");
     this.subscribe(() => {
@@ -886,7 +1061,9 @@ ${identity}`;
         origin,
         receivedAt: Date.now()
       });
-      this.debug("auth message missing game identity; falling back to anonymous tracking");
+      this.debug(
+        "auth message missing game identity; falling back to anonymous tracking"
+      );
       this.activateAnonymousMode();
       return;
     }
@@ -900,10 +1077,13 @@ ${identity}`;
         origin,
         receivedAt: Date.now()
       });
-      this.debug("auth message missing jwt; falling back to anonymous tracking", {
-        gameId: resolvedGameId,
-        apiUrl: resolvedApiUrl
-      });
+      this.debug(
+        "auth message missing jwt; falling back to anonymous tracking",
+        {
+          gameId: resolvedGameId,
+          apiUrl: resolvedApiUrl
+        }
+      );
       this.activateAnonymousMode();
       return;
     }
@@ -917,6 +1097,45 @@ ${identity}`;
       receivedAt: Date.now()
     });
   }
+  handleRequestAdsResult(data) {
+    if (data.type !== "LOOPLAY_ADS_WATCHED") return;
+    const requestId = toOptionalString(data.requestId);
+    if (!requestId) return;
+    const pending = this.pendingAdsRequests.get(requestId);
+    if (!pending) return;
+    this.pendingAdsRequests.delete(requestId);
+    if (pending.timer !== null) clearTimeout(pending.timer);
+    this.adsRequestInFlight = false;
+    this.debug("requestAds watched message received", { requestId });
+    pending.resolve(true);
+  }
+  handleRequestAdsUnavailable(data) {
+    if (data.type !== "LOOPLAY_ADS_UNAVAILABLE") return;
+    const requestId = toOptionalString(data.requestId);
+    if (!requestId) return;
+    const pending = this.pendingAdsRequests.get(requestId);
+    if (!pending) return;
+    this.pendingAdsRequests.delete(requestId);
+    if (pending.timer !== null) clearTimeout(pending.timer);
+    this.adsRequestInFlight = false;
+    this.debug("requestAds unavailable message received", { requestId });
+    pending.resolve(false);
+  }
+  handleIncomingMessage(data, origin) {
+    if (!isRecord(data)) return;
+    if (data.type === "LOOPLAY_AUTH") {
+      this.handleAuthMessage(data, origin);
+      return;
+    }
+    if (data.type === "LOOPLAY_ADS_WATCHED") {
+      this.handleRequestAdsResult(data);
+      return;
+    }
+    if (data.type === "LOOPLAY_ADS_UNAVAILABLE") {
+      this.handleRequestAdsUnavailable(data);
+      return;
+    }
+  }
   setState(next) {
     this.state = next;
     this.client = null;
@@ -941,6 +1160,35 @@ ${identity}`;
   debug(message, details) {
     this.options.onDebug?.(message, details);
   }
+  recordAutoRequestAdsActivity() {
+    this.autoAdsActionCount += 1;
+    const config = this.options.autoRequestAds;
+    if (!config?.enabled) return;
+    if (this.adsRequestInFlight) return;
+    if (!this.canTrack()) return;
+    const now = Date.now();
+    if (config.cooldownMs && now - this.lastAdsRequestAt < config.cooldownMs) {
+      return;
+    }
+    if (config.maxRequestsPerSession && this.adsRequestsSent >= config.maxRequestsPerSession) {
+      return;
+    }
+    const threshold = config.afterActionCount ?? 0;
+    const shouldRequest = threshold > 0 && this.autoAdsActionCount % threshold === 0;
+    if (!shouldRequest) return;
+    const chance = config.chance ?? 1;
+    if (chance <= 0 || Math.random() > chance) {
+      this.debug("auto requestAds skipped by chance", {
+        actionCount: this.autoAdsActionCount,
+        chance
+      });
+      return;
+    }
+    this.debug("auto requestAds triggered", {
+      actionCount: this.autoAdsActionCount
+    });
+    void this.requestAds();
+  }
 };
 
 exports.ApiClient = ApiClient;