@trillboards/ads-sdk 2.1.1 → 2.3.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/core/config.ts
-var SDK_VERSION = "2.1.1";
+var SDK_VERSION = "2.2.0";
 var DEFAULT_CONFIG = {
   API_BASE: "https://api.trillboards.com/v1/partner",
   CDN_BASE: "https://cdn.trillboards.com",
@@ -58,6 +58,7 @@ var DEFAULT_PUBLIC_STATE = {
   programmaticPlaying: false,
   prefetchedReady: false,
   waterfallMode: "programmatic_only",
+  adDeliveryProfileMode: null,
   screenId: null,
   deviceId: null
 };
@@ -85,6 +86,7 @@ function createInitialState() {
     programmaticRetryActive: false,
     programmaticRetryCount: 0,
     programmaticLastError: null,
+    adDeliveryProfile: null,
     initialized: false,
     screenOrientation: null,
     screenDimensions: null,
@@ -102,6 +104,7 @@ function getPublicState(internal) {
     programmaticPlaying: internal.programmaticPlaying,
     prefetchedReady: internal.prefetchedReady ?? false,
     waterfallMode: internal.waterfallMode,
+    adDeliveryProfileMode: internal.adDeliveryProfile?.mode ?? null,
     screenId: internal.screenId,
     deviceId: internal.deviceId
   };
@@ -362,10 +365,9 @@ var ApiClient = class {
     }
   }
   /**
-   * Ping the heartbeat endpoint to signal this device is alive.
-   * Returns `true` on 2xx, `false` on any error.
+   * Ping heartbeat endpoint and return delivery profile + queued commands.
    */
-  async sendHeartbeat(deviceId, screenId) {
+  async sendHeartbeat(deviceId, screenId, payload = {}) {
     logger.debug("Sending heartbeat", { deviceId });
     try {
       const response = await fetch(`${this.apiBase}/device/${deviceId}/heartbeat`, {
@@ -375,13 +377,24 @@ var ApiClient = class {
           device_id: deviceId,
           screen_id: screenId,
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          status: "active"
+          status: "active",
+          ...payload
         }),
         signal: AbortSignal.timeout(5e3)
       });
-      return response.ok;
+      if (!response.ok) {
+        return { ok: false, data: null };
+      }
+      let data = null;
+      try {
+        const json = await response.json();
+        data = json?.data ?? null;
+      } catch {
+        data = null;
+      }
+      return { ok: true, data };
     } catch {
-      return false;
+      return { ok: false, data: null };
     }
   }
   /**
@@ -934,7 +947,7 @@ var WaterfallEngine = class {
 };
 
 // src/player/ProgrammaticPlayer.ts
-var ProgrammaticPlayer = class {
+var _ProgrammaticPlayer = class _ProgrammaticPlayer {
   constructor(events, timeoutMs = 12e3) {
     // ── Public state ──────────────────────────────────────────
     this.vastTagUrl = null;
@@ -1021,8 +1034,11 @@ var ProgrammaticPlayer = class {
     this.telemetry.recordRequest();
     const correlator = Date.now();
     const finalUrl = vastUrl.includes("correlator=") ? vastUrl.replace(/correlator=[^&]*/, `correlator=${correlator}`) : `${vastUrl}${vastUrl.includes("?") ? "&" : "?"}correlator=${correlator}`;
-    if (typeof google === "undefined" || !google?.ima) {
-      onError("Google IMA SDK not loaded");
+    const imaReady = await this.ensureImaSdk();
+    if (!imaReady) {
+      const msg = "Google IMA SDK not loaded";
+      this.events.emit("programmatic_error", { error: msg, code: void 0 });
+      onError(msg);
       this.telemetry.recordError();
       this.waterfallEngine.recordFailure(sourceName);
       return;
@@ -1039,6 +1055,50 @@ var ProgrammaticPlayer = class {
       onError(err instanceof Error ? err.message : String(err));
     }
   }
+  /**
+   * Ensure Google IMA SDK is available. If already loaded, resolves
+   * immediately. Otherwise injects the `<script>` tag and waits.
+   * Matches the Lite SDK's `loadImaScript()` pattern.
+   */
+  async ensureImaSdk() {
+    if (typeof google !== "undefined" && google?.ima) return true;
+    if (typeof document === "undefined") return false;
+    const existing = document.querySelector(
+      `script[src="${_ProgrammaticPlayer.IMA_SDK_URL}"]`
+    );
+    if (existing) {
+      return new Promise((resolve) => {
+        const start = Date.now();
+        const check = () => {
+          if (typeof google !== "undefined" && google?.ima) {
+            resolve(true);
+          } else if (Date.now() - start > 5e3) {
+            resolve(false);
+          } else {
+            setTimeout(check, 100);
+          }
+        };
+        check();
+      });
+    }
+    if (!_ProgrammaticPlayer.imaLoadPromise) {
+      _ProgrammaticPlayer.imaLoadPromise = new Promise((resolve) => {
+        const script = document.createElement("script");
+        script.src = _ProgrammaticPlayer.IMA_SDK_URL;
+        script.async = true;
+        script.onload = () => {
+          _ProgrammaticPlayer.imaLoadPromise = null;
+          resolve(true);
+        };
+        script.onerror = () => {
+          _ProgrammaticPlayer.imaLoadPromise = null;
+          resolve(false);
+        };
+        document.head.appendChild(script);
+      });
+    }
+    return _ProgrammaticPlayer.imaLoadPromise;
+  }
   // ── IMA request / playback lifecycle ──────────────────────
   async requestAdsViaIMA(vastUrl, onComplete, onError) {
     return new Promise((resolve) => {
@@ -1240,6 +1300,12 @@ var ProgrammaticPlayer = class {
     this.telemetry.reset();
   }
 };
+// ── IMA SDK loader ──────────────────────────────────────────
+/** IMA script URL */
+_ProgrammaticPlayer.IMA_SDK_URL = "https://imasdk.googleapis.com/js/sdkloader/ima3.js";
+/** Singleton load promise so concurrent calls don't insert multiple scripts. */
+_ProgrammaticPlayer.imaLoadPromise = null;
+var ProgrammaticPlayer = _ProgrammaticPlayer;
 
 // src/player/Player.ts
 var MAX_AD_DURATION_SECONDS = 300;
@@ -1674,11 +1740,104 @@ var _TrillboardsAds = class _TrillboardsAds {
   }
   startHeartbeatTimer() {
     if (this.state.heartbeatTimer) clearInterval(this.state.heartbeatTimer);
+    const tick = () => {
+      this.sendHeartbeatTick().catch(() => {
+      });
+    };
+    tick();
     this.state.heartbeatTimer = setInterval(() => {
-      this.api.sendHeartbeat(this.config.deviceId, this.state.screenId);
+      tick();
     }, this.config.heartbeatInterval);
   }
+  async sendHeartbeatTick() {
+    const result = await this.api.sendHeartbeat(
+      this.config.deviceId,
+      this.state.screenId,
+      this.buildHeartbeatPayload()
+    );
+    if (!result.ok || !result.data) return;
+    if (result.data.ad_delivery_profile?.mode) {
+      this.applyAdDeliveryProfile(result.data.ad_delivery_profile);
+    }
+    if (Array.isArray(result.data.commands) && result.data.commands.length > 0) {
+      this.runHeartbeatCommands(result.data.commands);
+    }
+  }
+  buildHeartbeatPayload() {
+    const userAgent = typeof navigator !== "undefined" ? navigator.userAgent : "";
+    const platform = typeof navigator !== "undefined" ? navigator.platform : null;
+    const connection = typeof navigator !== "undefined" ? navigator.connection : null;
+    const chromiumMatch = userAgent.match(/(?:Chrome|Chromium)\/(\d+)/i);
+    const chromiumMajor = chromiumMatch ? Number(chromiumMatch[1]) : void 0;
+    const imaSupported = typeof window !== "undefined" ? Boolean(window?.google?.ima) : null;
+    const telemetry = {
+      powerState: typeof document !== "undefined" && document.hidden ? "standby" : "on",
+      agentStatus: typeof document !== "undefined" && document.hidden ? "background" : "foreground",
+      os: platform || void 0,
+      agentVersion: SDK_VERSION,
+      ima_integration: "html5_webview",
+      ima_supported: imaSupported,
+      webview_chromium_major: Number.isFinite(chromiumMajor) ? chromiumMajor : void 0
+    };
+    const payload = {
+      telemetry,
+      sdk: {
+        version: SDK_VERSION,
+        ima_supported: imaSupported,
+        ima_integration: "html5_webview",
+        webview_chromium_major: Number.isFinite(chromiumMajor) ? chromiumMajor : void 0
+      },
+      device: {
+        os: platform || void 0,
+        model: userAgent || void 0
+      }
+    };
+    if (connection) {
+      payload.network = {
+        connectionType: connection.type || void 0,
+        effectiveType: connection.effectiveType || void 0,
+        downlinkMbps: typeof connection.downlink === "number" ? connection.downlink : void 0,
+        bandwidthMbps: typeof connection.downlink === "number" ? connection.downlink : void 0,
+        rtt: typeof connection.rtt === "number" ? connection.rtt : void 0,
+        latencyRtt: typeof connection.rtt === "number" ? connection.rtt : void 0,
+        saveData: typeof connection.saveData === "boolean" ? connection.saveData : void 0
+      };
+    }
+    return payload;
+  }
+  applyAdDeliveryProfile(profile) {
+    if (!profile?.mode) return;
+    const previousMode = this.state.adDeliveryProfile?.mode ?? null;
+    this.state.adDeliveryProfile = profile;
+    if (profile.mode === "vast_fallback" && this.state.programmaticPlaying) {
+      this.programmaticPlayer.stop({ silent: true });
+      this.state.programmaticPlaying = false;
+    }
+    if (previousMode !== profile.mode) {
+      this.emitStateChanged();
+    }
+  }
+  runHeartbeatCommands(commands) {
+    for (const command of commands) {
+      const name = String(command?.command || "").toLowerCase();
+      if (name === "refresh_ads") {
+        this.refresh().catch(() => {
+        });
+      } else if (name === "restart") {
+        if (typeof window !== "undefined" && typeof window.location?.reload === "function") {
+          window.location.reload();
+          return;
+        }
+        this.refresh().catch(() => {
+        });
+      }
+    }
+  }
   playNextAd() {
+    if (this.state.adDeliveryProfile?.mode === "vast_fallback" && this.state.ads.length > 0) {
+      this.playDirect();
+      return;
+    }
     const mode = this.state.waterfallMode;
     if (mode === "programmatic_only" || mode === "programmatic_then_direct") {
       this.playProgrammatic();
@@ -1693,13 +1852,20 @@ var _TrillboardsAds = class _TrillboardsAds {
     this.programmaticPlayer.play(
       () => {
         this.state.programmaticPlaying = false;
+        this.resetProgrammaticBackoff();
         this.emitStateChanged();
         this.scheduleProgrammaticRetry();
       },
       (error) => {
         this.state.programmaticPlaying = false;
         this.state.programmaticLastError = error;
-        this.state.programmaticRetryCount++;
+        const normalizedError = String(error || "").toLowerCase();
+        const isNoFillLike = normalizedError.includes("no fill") || normalizedError.includes("no ads vast response") || normalizedError.includes("waterfall_exhausted") || normalizedError === "throttled" || normalizedError === "busy";
+        if (isNoFillLike) {
+          this.state.programmaticRetryCount = 0;
+        } else {
+          this.state.programmaticRetryCount++;
+        }
         this.emitStateChanged();
         if (this.state.waterfallMode === "programmatic_then_direct" && this.state.ads.length > 0) {
           this.playDirect();
@@ -1821,12 +1987,12 @@ var TrillboardsError = class extends Error {
 var TrillboardsAuthenticationError = class extends TrillboardsError {
   constructor(message) {
     super(
-      message ?? "Invalid API key. Check your key at https://trillboards.com/developers",
+      message ?? "Invalid API key. Check your key at https://trillboards.com/support/developers",
       {
         type: "authentication_error",
         code: "invalid_api_key",
         statusCode: 401,
-        help: "https://trillboards.com/developers"
+        help: "https://trillboards.com/support/developers"
       }
     );
     this.name = "TrillboardsAuthenticationError";