@trillboards/ads-sdk 2.1.0 → 2.2.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/core/config.ts
-var SDK_VERSION = "2.1.0";
+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 };
     }
   }
   /**
@@ -1398,6 +1411,9 @@ var _TrillboardsAds = class _TrillboardsAds {
     this.offlineHandler = null;
     this.visibilityHandler = null;
     this.config = resolveConfig(config);
+    if (this.config.debug) {
+      setLogLevel("debug");
+    }
     this.state = createInitialState();
     this.events = new EventEmitter();
     this.api = new ApiClient(this.config.apiBase);
@@ -1671,11 +1687,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();
@@ -1690,13 +1799,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();
@@ -1806,6 +1922,7 @@ var TrillboardsAds = _TrillboardsAds;
 var TrillboardsError = class extends Error {
   constructor(message, options = {}) {
     super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
     this.name = "TrillboardsError";
     this.type = options.type ?? "api_error";
     this.code = options.code ?? "unknown_error";
@@ -1817,12 +1934,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";