@trillboards/ads-sdk 2.1.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@trillboards/ads-sdk` will be documented in this file.
 
+## [2.2.0] - 2026-02-24
+
+### Features
+- Heartbeat payloads now include runtime telemetry (`telemetry`, `sdk`, `device`, `network`) for partner-side device profiling.
+- SDK now consumes heartbeat `ad_delivery_profile` responses and prefers direct fallback playback when profile mode is `vast_fallback`.
+- SDK now executes queued heartbeat commands (`refresh_ads`, `restart`) delivered by the partner API polling channel.
+
+### Fixes
+- Programmatic retry/backoff now resets correctly on ad completion and no-fill-like errors to prevent runaway retry escalation.
+
 ## [2.1.1] - 2026-02-15
 
 ### Fixes

package/README.md

@@ -93,6 +93,14 @@ The `TrillboardsConfig` interface accepts the following options:
 | `refreshInterval` | `number` | `120000` | Ad refresh interval (ms) |
 | `cacheSize` | `number` | `10` | Max cached ads |
 
+## Heartbeat Telemetry and Delivery Profile
+
+Every heartbeat now includes runtime telemetry (`sdk`, `device`, `network`, `ad`) so the partner API can segment legacy devices and return an `ad_delivery_profile`.
+
+- `mode: "ima_sdk"` keeps normal IMA playback.
+- `mode: "vast_fallback"` indicates the SDK should prefer direct fallback playback when direct ads are available.
+- Heartbeat command polling now executes queued `refresh_ads` commands immediately.
+
 ## Debug Mode
 
 Enable debug logging to see all API requests, state transitions, and cache operations:
@@ -215,7 +223,7 @@ console.log('Tracked:', result.tracked);
 
 ## Links
 
-- [Developer documentation](https://trillboards.com/developers/partner-sdk)
+- [Developer documentation](https://trillboards.com/support/developers/partner-sdk)
 - [API reference](https://api.trillboards.com/docs/partner)
 
 ## License

package/dist/cli.js

@@ -28,7 +28,7 @@ var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
 
 // src/core/config.ts
-var SDK_VERSION = "2.1.1";
+var SDK_VERSION = "2.2.0";
 
 // src/cli.ts
 var BANNER = `
@@ -127,7 +127,7 @@ async function runInit() {
     console.log("  Next steps:");
     console.log("    1. Register more devices: POST /v1/partner/device");
     console.log("    2. Connect Stripe for payouts: POST /v1/partner/stripe/connect");
-    console.log("    3. Read the docs: https://trillboards.com/developers");
+    console.log("    3. Read the docs: https://trillboards.com/support/developers");
     console.log("");
     completed = true;
   } catch (err) {

package/dist/index.d.mts

@@ -59,6 +59,7 @@ interface TrillboardsState {
     programmaticPlaying: boolean;
     prefetchedReady: boolean;
     waterfallMode: WaterfallMode;
+    adDeliveryProfileMode: AdDeliveryMode | null;
     screenId: string | null;
     deviceId: string | null;
 }
@@ -113,6 +114,37 @@ interface CircuitBreakerState {
     consecutiveFailures: number;
     openUntil: number;
 }
+type AdDeliveryMode = 'ima_sdk' | 'vast_fallback';
+interface AdDeliveryProfile {
+    mode: AdDeliveryMode;
+    reason?: string;
+    auto_recovery_enabled?: boolean;
+    ima_integration?: 'android_native' | 'html5_webview' | 'disabled' | 'unknown';
+    android_api_level?: number | null;
+    webview_chromium_major?: number | null;
+    notes?: string[];
+}
+interface HeartbeatCommand {
+    id: string;
+    command: string;
+    payload?: Record<string, unknown>;
+    queued_at?: string;
+}
+interface HeartbeatResponseData {
+    status?: 'online' | 'offline' | string;
+    last_seen_at?: string;
+    ad_delivery_profile?: AdDeliveryProfile;
+    commands?: HeartbeatCommand[];
+}
+interface HeartbeatPayload {
+    telemetry?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    sdk?: Record<string, unknown>;
+    device?: Record<string, unknown>;
+    network?: Record<string, unknown>;
+    ad?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 interface FetchAdsResult {
     ads: AdItem[];
     settings: Record<string, unknown>;
@@ -260,6 +292,10 @@ declare class TrillboardsAds {
     private refreshAds;
     private startRefreshTimer;
     private startHeartbeatTimer;
+    private sendHeartbeatTick;
+    private buildHeartbeatPayload;
+    private applyAdDeliveryProfile;
+    private runHeartbeatCommands;
     private playNextAd;
     private playProgrammatic;
     private playDirect;
@@ -317,7 +353,7 @@ declare class EventEmitter {
 }
 
 /** Single source of truth for the SDK version string. */
-declare const SDK_VERSION = "2.1.1";
+declare const SDK_VERSION = "2.2.0";
 /**
  * Compile-time constants that mirror the original IIFE CONFIG
  * object. Every value here acts as a sensible production default
@@ -336,7 +372,7 @@ declare const DEFAULT_CONFIG: {
     readonly PROGRAMMATIC_MIN_INTERVAL_MS: 5000;
     readonly PROGRAMMATIC_RETRY_MS: 5000;
     readonly PROGRAMMATIC_BACKOFF_MAX_MS: number;
-    readonly VERSION: "2.1.1";
+    readonly VERSION: "2.2.0";
 };
 /**
  * Merge a caller-supplied TrillboardsConfig with the defaults,
@@ -392,6 +428,7 @@ interface InternalState {
     programmaticRetryActive: boolean;
     programmaticRetryCount: number;
     programmaticLastError: string | null;
+    adDeliveryProfile: AdDeliveryProfile | null;
     initialized: boolean;
     screenOrientation: string | null;
     screenDimensions: ScreenDimensions | null;
@@ -537,6 +574,10 @@ declare class WaterfallEngine {
     recordFailure(sourceName: string): void;
 }
 
+interface HeartbeatResult {
+    ok: boolean;
+    data: HeartbeatResponseData | null;
+}
 /**
  * Low-level HTTP client for the Trillboards Partner API.
  *
@@ -580,10 +621,9 @@ declare class ApiClient {
         completed: boolean;
     }): Promise<boolean>;
     /**
-     * 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.
      */
-    sendHeartbeat(deviceId: string, screenId: string | null): Promise<boolean>;
+    sendHeartbeat(deviceId: string, screenId: string | null, payload?: HeartbeatPayload): Promise<HeartbeatResult>;
     /**
      * Report a programmatic lifecycle event (VAST fill, timeout,
      * error, etc.) to the analytics backend.

package/dist/index.d.ts

@@ -59,6 +59,7 @@ interface TrillboardsState {
     programmaticPlaying: boolean;
     prefetchedReady: boolean;
     waterfallMode: WaterfallMode;
+    adDeliveryProfileMode: AdDeliveryMode | null;
     screenId: string | null;
     deviceId: string | null;
 }
@@ -113,6 +114,37 @@ interface CircuitBreakerState {
     consecutiveFailures: number;
     openUntil: number;
 }
+type AdDeliveryMode = 'ima_sdk' | 'vast_fallback';
+interface AdDeliveryProfile {
+    mode: AdDeliveryMode;
+    reason?: string;
+    auto_recovery_enabled?: boolean;
+    ima_integration?: 'android_native' | 'html5_webview' | 'disabled' | 'unknown';
+    android_api_level?: number | null;
+    webview_chromium_major?: number | null;
+    notes?: string[];
+}
+interface HeartbeatCommand {
+    id: string;
+    command: string;
+    payload?: Record<string, unknown>;
+    queued_at?: string;
+}
+interface HeartbeatResponseData {
+    status?: 'online' | 'offline' | string;
+    last_seen_at?: string;
+    ad_delivery_profile?: AdDeliveryProfile;
+    commands?: HeartbeatCommand[];
+}
+interface HeartbeatPayload {
+    telemetry?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    sdk?: Record<string, unknown>;
+    device?: Record<string, unknown>;
+    network?: Record<string, unknown>;
+    ad?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 interface FetchAdsResult {
     ads: AdItem[];
     settings: Record<string, unknown>;
@@ -260,6 +292,10 @@ declare class TrillboardsAds {
     private refreshAds;
     private startRefreshTimer;
     private startHeartbeatTimer;
+    private sendHeartbeatTick;
+    private buildHeartbeatPayload;
+    private applyAdDeliveryProfile;
+    private runHeartbeatCommands;
     private playNextAd;
     private playProgrammatic;
     private playDirect;
@@ -317,7 +353,7 @@ declare class EventEmitter {
 }
 
 /** Single source of truth for the SDK version string. */
-declare const SDK_VERSION = "2.1.1";
+declare const SDK_VERSION = "2.2.0";
 /**
  * Compile-time constants that mirror the original IIFE CONFIG
  * object. Every value here acts as a sensible production default
@@ -336,7 +372,7 @@ declare const DEFAULT_CONFIG: {
     readonly PROGRAMMATIC_MIN_INTERVAL_MS: 5000;
     readonly PROGRAMMATIC_RETRY_MS: 5000;
     readonly PROGRAMMATIC_BACKOFF_MAX_MS: number;
-    readonly VERSION: "2.1.1";
+    readonly VERSION: "2.2.0";
 };
 /**
  * Merge a caller-supplied TrillboardsConfig with the defaults,
@@ -392,6 +428,7 @@ interface InternalState {
     programmaticRetryActive: boolean;
     programmaticRetryCount: number;
     programmaticLastError: string | null;
+    adDeliveryProfile: AdDeliveryProfile | null;
     initialized: boolean;
     screenOrientation: string | null;
     screenDimensions: ScreenDimensions | null;
@@ -537,6 +574,10 @@ declare class WaterfallEngine {
     recordFailure(sourceName: string): void;
 }
 
+interface HeartbeatResult {
+    ok: boolean;
+    data: HeartbeatResponseData | null;
+}
 /**
  * Low-level HTTP client for the Trillboards Partner API.
  *
@@ -580,10 +621,9 @@ declare class ApiClient {
         completed: boolean;
     }): Promise<boolean>;
     /**
-     * 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.
      */
-    sendHeartbeat(deviceId: string, screenId: string | null): Promise<boolean>;
+    sendHeartbeat(deviceId: string, screenId: string | null, payload?: HeartbeatPayload): Promise<HeartbeatResult>;
     /**
      * Report a programmatic lifecycle event (VAST fill, timeout,
      * error, etc.) to the analytics backend.

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // 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",
@@ -60,6 +60,7 @@ var DEFAULT_PUBLIC_STATE = {
   programmaticPlaying: false,
   prefetchedReady: false,
   waterfallMode: "programmatic_only",
+  adDeliveryProfileMode: null,
   screenId: null,
   deviceId: null
 };
@@ -87,6 +88,7 @@ function createInitialState() {
     programmaticRetryActive: false,
     programmaticRetryCount: 0,
     programmaticLastError: null,
+    adDeliveryProfile: null,
     initialized: false,
     screenOrientation: null,
     screenDimensions: null,
@@ -104,6 +106,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
   };
@@ -364,10 +367,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`, {
@@ -377,13 +379,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 };
     }
   }
   /**
@@ -936,7 +949,7 @@ var WaterfallEngine = class {
 };
 
 // src/player/ProgrammaticPlayer.ts
-var ProgrammaticPlayer = class {
+var _ProgrammaticPlayer = class _ProgrammaticPlayer {
   constructor(events, timeoutMs = 12e3) {
     // ── Public state ──────────────────────────────────────────
     this.vastTagUrl = null;
@@ -1023,8 +1036,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;
@@ -1041,6 +1057,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) => {
@@ -1242,6 +1302,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;
@@ -1676,11 +1742,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();
@@ -1695,13 +1854,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();
@@ -1823,12 +1989,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";