@hyve-sdk/js 2.11.2 → 2.13.0-canary.0

package/dist/react.mjs

@@ -148,6 +148,12 @@ function parseUrlParams(searchParams) {
 var NativeBridge = class {
   static handlers = /* @__PURE__ */ new Map();
   static isInitialized = false;
+  /**
+   * Pending `sendAdRequest()` promises, keyed by the ad type native echoes
+   * back in `AD_RESULT.type` ("rewarded" | "interstitial"). One in-flight
+   * request per type — ads are shown sequentially.
+   */
+  static adResultResolvers = /* @__PURE__ */ new Map();
   /**
    * Checks if the app is running inside a React Native WebView
    */
@@ -200,16 +206,20 @@ var NativeBridge = class {
         "PUSH_PERMISSION_DENIED" /* PUSH_PERMISSION_DENIED */,
         "PRODUCTS_RESULT" /* PRODUCTS_RESULT */,
         "PURCHASE_COMPLETE" /* PURCHASE_COMPLETE */,
-        "PURCHASE_ERROR" /* PURCHASE_ERROR */
+        "PURCHASE_ERROR" /* PURCHASE_ERROR */,
+        "AD_RESULT" /* AD_RESULT */
       ];
       if (!nativeResponseTypes.includes(data.type)) {
         return;
       }
+      if (data.type === "AD_RESULT" /* AD_RESULT */) {
+        this.resolveAdResult(data.payload);
+      }
       const handler = this.handlers.get(data.type);
       if (handler) {
         logger.debug(`[NativeBridge] Handling message: ${data.type}`);
         handler(data.payload);
-      } else {
+      } else if (data.type !== "AD_RESULT" /* AD_RESULT */) {
         logger.warn(`[NativeBridge] No handler registered for: ${data.type}`);
       }
     } catch (error) {
@@ -335,6 +345,81 @@ var NativeBridge = class {
   static purchase(productId, userId) {
     this.send("PURCHASE" /* PURCHASE */, { productId, userId });
   }
+  /**
+   * Sends a native ad request and resolves with the `AD_RESULT` native sends
+   * back. Never rejects — a missing native context, timeout, or superseded
+   * request resolves to `{ success: false }` with an error code so callers can
+   * decide whether to fall back to the web ad path.
+   *
+   * @param messageType - `SHOW_REWARDED_AD` or `SHOW_INTERSTITIAL_AD`
+   * @param payload - `{ gameId, format, placement? }`
+   * @param timeoutMs - How long to wait for `AD_RESULT` before giving up
+   *
+   * @example
+   * const result = await NativeBridge.sendAdRequest(
+   *   NativeMessageType.SHOW_REWARDED_AD,
+   *   { gameId: "123", format: "rewarded", placement: "level_end" },
+   * );
+   * if (result.success) grantReward();
+   */
+  static sendAdRequest(messageType, payload, timeoutMs = 12e4) {
+    const expectedType = messageType === "SHOW_REWARDED_AD" /* SHOW_REWARDED_AD */ ? "rewarded" : "interstitial";
+    return new Promise((resolve) => {
+      if (!this.isNativeContext()) {
+        resolve({ type: expectedType, success: false, error: "no_native_context" });
+        return;
+      }
+      this.initialize();
+      const existing = this.adResultResolvers.get(expectedType);
+      if (existing) {
+        logger.warn(`[NativeBridge] Superseding in-flight ${expectedType} ad request`);
+        existing({ type: expectedType, success: false, error: "superseded" });
+      }
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.adResultResolvers.delete(expectedType);
+        logger.warn(`[NativeBridge] Ad request timed out: ${expectedType}`);
+        resolve({ type: expectedType, success: false, error: "timeout" });
+      }, timeoutMs);
+      this.adResultResolvers.set(expectedType, (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.adResultResolvers.delete(expectedType);
+        resolve(result);
+      });
+      this.send(messageType, payload);
+    });
+  }
+  /**
+   * Registers a handler invoked for every `AD_RESULT` message from native,
+   * in addition to resolving any pending {@link sendAdRequest} promise.
+   * Useful for diagnostics or availability tracking.
+   *
+   * @param handler - Called with the raw `AD_RESULT` payload
+   */
+  static onAdResult(handler) {
+    this.on("AD_RESULT" /* AD_RESULT */, handler);
+  }
+  /**
+   * Resolves the pending {@link sendAdRequest} promise that matches an
+   * incoming `AD_RESULT` payload. No-op when nothing is waiting (e.g. a late
+   * result after a timeout).
+   */
+  static resolveAdResult(payload) {
+    if (!payload?.type) {
+      logger.warn("[NativeBridge] AD_RESULT received without a type");
+      return;
+    }
+    const resolver = this.adResultResolvers.get(payload.type);
+    if (resolver) {
+      resolver(payload);
+    } else {
+      logger.debug(`[NativeBridge] No pending ad request for: ${payload.type}`);
+    }
+  }
 };
 
 // src/utils/jwt.ts
@@ -691,10 +776,12 @@ function getAttributionData() {
 }
 
 // src/services/ads.ts
+var FALLBACK_ERROR_CODES = ["not_configured", "config_fetch_failed"];
 var AdsService = class {
   config = {
     sound: "on",
     debug: false,
+    useNativeAds: false,
     onBeforeAd: () => {
     },
     onAfterAd: () => {
@@ -705,6 +792,16 @@ var AdsService = class {
   // Cached init promise — ensures adConfig() is only called once
   initPromise = null;
   ready = false;
+  // Game this SDK instance serves — sent to native so it can resolve unit IDs.
+  // The SDK never stores or resolves unit IDs itself (Decision 7).
+  gameId = null;
+  /**
+   * Set the game ID used in native ad requests. Called by the client once the
+   * game ID is known (from URL params or JWT). No-op for the web ad path.
+   */
+  setGameId(gameId) {
+    this.gameId = gameId;
+  }
   /**
    * Optionally configure the ads service.
    * Not required — ads work without calling this.
@@ -718,7 +815,10 @@ var AdsService = class {
       onRewardEarned: config.onRewardEarned ?? this.config.onRewardEarned
     };
     if (this.config.debug) {
-      logger.debug("[AdsService] Configuration updated:", { sound: this.config.sound });
+      logger.debug("[AdsService] Configuration updated:", {
+        sound: this.config.sound,
+        useNativeAds: this.config.useNativeAds
+      });
     }
   }
   /**
@@ -755,10 +855,93 @@ var AdsService = class {
   }
   /**
    * Show an ad. Auto-initializes on the first call.
-   * Returns immediately with success: false if ads are disabled or unavailable.
+   *
+   * Inside the Hyve mobile shell (`window.ReactNativeWebView` present) with
+   * `useNativeAds` enabled, the request is routed to native AdMob via the
+   * bridge. Otherwise — or when native reports the slot is `not_configured` /
+   * `config_fetch_failed` — it falls back to the Google H5 web path.
+   *
+   * Returns `success: false` if ads are disabled or unavailable.
+   *
+   * @param type - Ad type to show
+   * @param placement - Optional placement key, forwarded to native; ignored on
+   *   the web path (H5 has no placement concept).
    */
-  async show(type) {
+  async show(type, placement) {
     const requestedAt = Date.now();
+    if (this.isNativeAdsContext()) {
+      const nativeResult = await this.showNative(type, placement, requestedAt);
+      if (nativeResult) return nativeResult;
+    }
+    return this.showWeb(type, requestedAt, true);
+  }
+  /**
+   * True when running inside the Hyve mobile shell with native ads enabled.
+   */
+  isNativeAdsContext() {
+    return NativeBridge.isNativeContext() && this.config.useNativeAds === true;
+  }
+  /**
+   * Route an ad request to native AdMob via the bridge (Decision 7 — native
+   * owns unit-ID resolution; the SDK only sends `{ gameId, format, placement }`).
+   *
+   * Returns the resolved `AdResult`, or `null` to indicate the caller should
+   * fall back to the web ad path for this single call.
+   */
+  async showNative(type, placement, requestedAt) {
+    if (!this.gameId) {
+      if (this.config.debug) {
+        logger.debug("[AdsService] Native ads enabled but no gameId set \u2014 using web path");
+      }
+      return null;
+    }
+    const format = type === "rewarded" ? "rewarded" : "interstitial";
+    const messageType = type === "rewarded" ? "SHOW_REWARDED_AD" /* SHOW_REWARDED_AD */ : "SHOW_INTERSTITIAL_AD" /* SHOW_INTERSTITIAL_AD */;
+    if (this.config.debug) {
+      logger.debug(`[AdsService] Requesting native ${type} ad (format: ${format})`, {
+        gameId: this.gameId,
+        placement
+      });
+    }
+    this.config.onBeforeAd(type);
+    const result = await NativeBridge.sendAdRequest(messageType, {
+      gameId: this.gameId,
+      format,
+      placement
+    });
+    const completedAt = Date.now();
+    if (result.error && FALLBACK_ERROR_CODES.includes(result.error)) {
+      if (this.config.debug) {
+        logger.debug(`[AdsService] Native ad ${result.error} \u2014 falling back to web path`);
+      }
+      return this.showWeb(type, requestedAt, false);
+    }
+    this.config.onAfterAd(type);
+    if (type === "rewarded" && result.success) {
+      this.config.onRewardEarned();
+    }
+    if (this.config.debug) {
+      logger.debug("[AdsService] Native ad result:", {
+        type,
+        success: result.success,
+        error: result.error
+      });
+    }
+    return {
+      success: result.success,
+      type,
+      error: result.error ? new Error(result.error) : void 0,
+      requestedAt,
+      completedAt
+    };
+  }
+  /**
+   * Show an ad via the Google H5 web path. Auto-initializes on first call.
+   *
+   * @param fireBeforeAd - When false, `onBeforeAd` is not fired (the native
+   *   fallback path already fired it before delegating here).
+   */
+  async showWeb(type, requestedAt, fireBeforeAd) {
     const ready = await this.initialize();
     if (!ready || !window.adBreak) {
       return {
@@ -769,12 +952,15 @@ var AdsService = class {
         completedAt: Date.now()
       };
     }
-    return this.showAdBreak(type);
+    return this.showAdBreak(type, fireBeforeAd);
   }
   /**
    * Show an ad break via the Google H5 API.
+   *
+   * @param fireBeforeAd - When false, skips `onBeforeAd` (already fired by the
+   *   native fallback path that delegated here).
    */
-  async showAdBreak(type) {
+  async showAdBreak(type, fireBeforeAd = true) {
     const requestedAt = Date.now();
     return new Promise((resolve) => {
       const googleType = type === "rewarded" ? "reward" : type === "preroll" ? "start" : "next";
@@ -782,7 +968,9 @@ var AdsService = class {
       if (this.config.debug) {
         logger.debug(`[AdsService] Showing ${type} ad`);
       }
-      this.config.onBeforeAd(type);
+      if (fireBeforeAd) {
+        this.config.onBeforeAd(type);
+      }
       const adBreakConfig = {
         type: googleType,
         name: adName,
@@ -1950,6 +2138,7 @@ var HyveClient = class {
         this.gameId = params.gameId;
         logger.info("Game ID extracted from game-id parameter:", this.gameId);
       }
+      this.adsService.setGameId(this.gameId);
       if (this.jwtToken) {
         logger.info("Authentication successful via JWT");
       } else {
@@ -2055,6 +2244,93 @@ var HyveClient = class {
       return false;
     }
   }
+  /**
+   * Required lifecycle telemetry — Session start.
+   * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
+   */
+  async sessionStart() {
+    return this.sendTelemetry("game", "session", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Session end.
+   */
+  async sessionEnd() {
+    return this.sendTelemetry("game", "session", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby loading start.
+   */
+  async lobbyLoadingStart() {
+    return this.sendTelemetry("game", "loading", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby loading end.
+   */
+  async lobbyLoadingEnd() {
+    return this.sendTelemetry("game", "loading", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Game loading start.
+   */
+  async gameLoadingStart() {
+    return this.sendTelemetry("game", "game_loading", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Game loading end.
+   */
+  async gameLoadingEnd() {
+    return this.sendTelemetry("game", "game_loading", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Lobby initialization.
+   */
+  async lobbyInit() {
+    return this.sendTelemetry("game", "lobby", "init");
+  }
+  /**
+   * Required lifecycle telemetry — Gameplay end.
+   * Also notifies CrazyGames that gameplay has stopped.
+   */
+  async gameplayEnd() {
+    if (this.crazyGamesService) {
+      if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
+      this.crazyGamesService.gameplayStop();
+    }
+    return this.sendTelemetry("game", "gameplay", "end");
+  }
+  /**
+   * Required lifecycle telemetry — Store opened.
+   */
+  async storeOpen() {
+    return this.sendTelemetry("game", "store", "start");
+  }
+  /**
+   * Required lifecycle telemetry — Purchase complete.
+   * @param itemName Name of the purchased item (required by the platform)
+   */
+  async purchaseComplete(itemName) {
+    return this.sendTelemetry("game", "purchase", "complete", null, null, {
+      item_name: itemName
+    });
+  }
+  /**
+   * Required lifecycle telemetry — Purchase failed.
+   * @param itemName Name of the item the purchase was for
+   */
+  async purchaseFail(itemName) {
+    return this.sendTelemetry("game", "purchase", "fail", null, null, {
+      item_name: itemName
+    });
+  }
+  /**
+   * Required lifecycle telemetry — Purchase cancelled.
+   * @param itemName Name of the item the purchase was for
+   */
+  async purchaseCancel(itemName) {
+    return this.sendTelemetry("game", "purchase", "cancel", null, null, {
+      item_name: itemName
+    });
+  }
   /**
    * Makes an authenticated API call using the JWT token
    * @param endpoint API endpoint path (will be appended to base URL)
@@ -2176,6 +2452,7 @@ var HyveClient = class {
     this.userId = null;
     this.jwtToken = null;
     this.gameId = null;
+    this.adsService.setGameId(null);
     logger.info("User logged out");
   }
   /**
@@ -2350,9 +2627,11 @@ var HyveClient = class {
   /**
    * Show an ad
    * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
+   * @param placement Optional placement key, forwarded to the native AdMob path
+   *   to resolve a per-placement unit ID. Ignored on the web (H5/Playgama) path.
    * @returns Promise resolving to ad result
    */
-  async showAd(type) {
+  async showAd(type, placement) {
     if (this.crazyGamesService) {
       if (this.crazyGamesInitPromise) {
         await this.crazyGamesInitPromise;
@@ -2391,17 +2670,18 @@ var HyveClient = class {
         });
       }
     }
-    return this.adsService.show(type);
+    return this.adsService.show(type, placement);
   }
   /**
-   * Notifies CrazyGames that gameplay has started.
-   * No-op on other platforms.
+   * Required lifecycle telemetry — Gameplay start.
+   * Also notifies CrazyGames that gameplay has started.
    */
   async gameplayStart() {
     if (this.crazyGamesService) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
       this.crazyGamesService.gameplayStart();
     }
+    return this.sendTelemetry("game", "gameplay", "start");
   }
   /**
    * Notifies CrazyGames that gameplay has stopped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "2.11.2",
+  "version": "2.13.0-canary.0",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {
@@ -27,14 +27,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "lint": "eslint . --max-warnings 0",
-    "check-types": "tsc --noEmit",
-    "build": "tsup",
-    "prepublishOnly": "pnpm run build && pnpm run check-types",
-    "publish:npm": "pnpm publish --access public",
-    "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
-  },
   "keywords": [
     "hyve",
     "game",
@@ -71,12 +63,23 @@
     }
   },
   "devDependencies": {
-    "@repo/eslint-config": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
     "@types/minimatch": "^5.1.2",
     "@types/react": "^18.3.28",
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.8",
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check-types": "tsc --noEmit",
+    "build": "tsup",
+    "publish:npm": "pnpm publish --access public",
+    "publish:canary": "pnpm publish --access public --tag canary --no-git-checks",
+    "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
   }
-}
+}