@trillboards/ads-sdk 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,602 @@
+interface TrillboardsConfig {
+    deviceId: string;
+    apiBase?: string;
+    cdnBase?: string;
+    waterfall?: WaterfallMode;
+    autoStart?: boolean;
+    refreshInterval?: number;
+    heartbeatInterval?: number;
+    defaultImageDuration?: number;
+    defaultAdInterval?: number;
+    programmaticTimeout?: number;
+    programmaticMinInterval?: number;
+    programmaticRetry?: number;
+    programmaticBackoffMax?: number;
+    cacheSize?: number;
+}
+type WaterfallMode = 'programmatic_only' | 'programmatic_then_direct' | 'direct_only';
+interface AdItem {
+    id: string;
+    allocation_id?: string;
+    type: 'image' | 'video';
+    media_url: string;
+    /** Duration in seconds */
+    duration: number;
+    title?: string;
+    impression_id: string;
+    tracking?: {
+        impression_url: string;
+        complete_url: string;
+    };
+}
+interface ProgrammaticSettings {
+    vast_tag_url: string | null;
+    variant_name: string | null;
+    min_interval_seconds?: number;
+    sources?: VastSource[];
+    auction_winner?: AuctionWinner | null;
+}
+interface VastSource {
+    name: string;
+    vast_url: string;
+    priority: number;
+    timeout_ms: number;
+    enabled: boolean;
+}
+interface AuctionWinner {
+    source: string;
+    bid_price_cpm?: number;
+    vast_url: string;
+}
+interface TrillboardsState {
+    initialized: boolean;
+    isPlaying: boolean;
+    isPaused: boolean;
+    isOffline: boolean;
+    currentAd: AdItem | null;
+    adCount: number;
+    programmaticPlaying: boolean;
+    prefetchedReady: boolean;
+    waterfallMode: WaterfallMode;
+    screenId: string | null;
+    deviceId: string | null;
+}
+interface ScreenDimensions {
+    width: number;
+    height: number;
+    orientation?: 'portrait' | 'landscape';
+}
+interface PlayerTruth {
+    slotWidth: number | null;
+    slotHeight: number | null;
+    orientation: 'portrait' | 'landscape' | null;
+    muted: boolean;
+    autoplayAllowed: boolean;
+    userAgent: string | null;
+}
+interface ImpressionData {
+    adId: string;
+    impressionId: string;
+    deviceId: string;
+    screenId?: string;
+    allocationId?: string;
+    duration: number;
+    completed: boolean;
+    timestamp: string;
+    type?: 'direct' | 'programmatic';
+}
+interface BridgeConfig {
+    send: (event: string, data: unknown) => void;
+    receive?: (callback: (command: unknown) => void) => void;
+    events?: string[];
+    name?: string;
+}
+type BridgeType = 'android' | 'android-alt' | 'ios' | 'react-native' | 'flutter' | 'ctv' | 'electron' | 'tauri' | 'postMessage' | 'custom';
+interface BridgePayload {
+    type: 'trillboards';
+    version: string;
+    event: string;
+    data: unknown;
+    timestamp: number;
+    deviceId: string | null;
+    screenId: string | null;
+    sessionId: string;
+}
+interface TelemetrySnapshot {
+    fill_rate: number;
+    no_fill_rate: number;
+    timeout_rate: number;
+    error_rate: number;
+}
+interface CircuitBreakerState {
+    consecutiveFailures: number;
+    openUntil: number;
+}
+interface FetchAdsResult {
+    ads: AdItem[];
+    settings: Record<string, unknown>;
+    programmatic: ProgrammaticSettings | null;
+    screenId: string | null;
+    screenOrientation: string | null;
+    screenDimensions: ScreenDimensions | null;
+    etag: string | null;
+    notModified: boolean;
+}
+interface EventMap {
+    initialized: {
+        deviceId: string;
+    };
+    ads_refreshed: {
+        count: number;
+    };
+    ads_loaded_from_cache: {
+        count: number;
+    };
+    ad_started: {
+        id: string;
+        type: string;
+        index: number;
+    };
+    ad_ended: {
+        id: string;
+        type: string;
+        duration: number;
+    };
+    ad_ready: {
+        type: 'programmatic' | 'direct';
+        source?: string;
+    };
+    ad_error: {
+        error: string;
+        source?: string;
+    };
+    programmatic_started: {
+        source: string;
+        variant: string | null;
+    };
+    programmatic_ended: {
+        source: string;
+        variant: string | null;
+        duration: number;
+    };
+    programmatic_error: {
+        error: string;
+        code?: number;
+    };
+    programmatic_no_fill: {
+        source: string;
+    };
+    programmatic_timeout: {
+        source: string;
+    };
+    impression_tracked: {
+        adId: string;
+        impressionId: string;
+    };
+    state_changed: TrillboardsState;
+    bridge_event: {
+        event: string;
+        data: unknown;
+    };
+    visibility_changed: {
+        visible: boolean;
+    };
+    offline: Record<string, never>;
+    online: Record<string, never>;
+}
+
+declare class TrillboardsAds {
+    /** Singleton reference — `create()` destroys any previous instance. */
+    private static _instance;
+    private config;
+    private state;
+    private events;
+    private api;
+    private cache;
+    private bridge;
+    private programmaticPlayer;
+    private directPlayer;
+    /** Stored references for window event listeners (cleanup in destroy). */
+    private onlineHandler;
+    private offlineHandler;
+    private visibilityHandler;
+    private constructor();
+    /**
+     * Create and initialize a new TrillboardsAds instance.
+     * If a previous instance exists, it is destroyed first
+     * (singleton guard).
+     */
+    static create(config: TrillboardsConfig): Promise<TrillboardsAds>;
+    /**
+     * Initialize the SDK (private — called by `create()` only).
+     */
+    private init;
+    /**
+     * Destroy the SDK instance and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * Show the ad container and start playback.
+     */
+    show(): void;
+    /**
+     * Hide the ad container and pause playback.
+     */
+    hide(): void;
+    /**
+     * Skip the current ad.
+     */
+    skipAd(): void;
+    /**
+     * Force refresh — re-fetches VAST URLs from server with null etag.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Prefetch the next ad for instant playback.
+     */
+    prefetchNextAd(): Promise<void>;
+    /**
+     * Get current public state.
+     */
+    getState(): TrillboardsState;
+    /**
+     * Get current ad list.
+     */
+    getAds(): AdItem[];
+    /**
+     * Subscribe to an event.
+     */
+    on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    /**
+     * Unsubscribe from an event.
+     */
+    off<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    /**
+     * Register a custom native bridge.
+     */
+    registerBridge(config: BridgeConfig): boolean;
+    private createContainer;
+    private refreshAds;
+    private startRefreshTimer;
+    private startHeartbeatTimer;
+    private playNextAd;
+    private playProgrammatic;
+    private playDirect;
+    private scheduleNextDirect;
+    private scheduleProgrammaticRetry;
+    private resetProgrammaticBackoff;
+    private emitStateChanged;
+    private handleBridgeCommand;
+}
+
+type Handler<T> = (data: T) => void;
+/**
+ * A lightweight, fully-typed event emitter.
+ *
+ * Usage:
+ * ```ts
+ * const emitter = new EventEmitter();
+ * emitter.on('ad_started', ({ id, type, index }) => { ... });
+ * emitter.emit('ad_started', { id: '123', type: 'video', index: 0 });
+ * ```
+ *
+ * Handler errors are caught and logged so a single bad listener
+ * can never crash the SDK or block other listeners.
+ */
+declare class EventEmitter {
+    private handlers;
+    /**
+     * Register a handler for the given event.
+     * The same handler reference can only be registered once per
+     * event (Set semantics).
+     */
+    on<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): void;
+    /**
+     * Remove a previously registered handler.
+     * No-op if the handler was never registered.
+     */
+    off<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): void;
+    /**
+     * Emit an event, invoking every registered handler with the
+     * supplied data payload. Handlers are called synchronously in
+     * registration order. Exceptions inside handlers are caught
+     * and logged to the console so they never propagate.
+     */
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+    /**
+     * Register a one-shot handler that automatically removes itself
+     * after the first invocation.
+     */
+    once<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): void;
+    /**
+     * Remove all handlers for all events.
+     * Typically called during SDK teardown / destroy.
+     */
+    removeAllListeners(): void;
+}
+
+/** Single source of truth for the SDK version string. */
+declare const SDK_VERSION = "2.0.0";
+/**
+ * Compile-time constants that mirror the original IIFE CONFIG
+ * object. Every value here acts as a sensible production default
+ * that can be overridden per-device via TrillboardsConfig.
+ */
+declare const DEFAULT_CONFIG: {
+    readonly API_BASE: "https://api.trillboards.com/v1/partner";
+    readonly CDN_BASE: "https://cdn.trillboards.com";
+    readonly CACHE_NAME: "trillboards-lite-ads";
+    readonly CACHE_SIZE: 10;
+    readonly REFRESH_INTERVAL: number;
+    readonly HEARTBEAT_INTERVAL: number;
+    readonly DEFAULT_IMAGE_DURATION: 8000;
+    readonly DEFAULT_AD_INTERVAL: 60000;
+    readonly PROGRAMMATIC_TIMEOUT_MS: 12000;
+    readonly PROGRAMMATIC_MIN_INTERVAL_MS: 5000;
+    readonly PROGRAMMATIC_RETRY_MS: 5000;
+    readonly PROGRAMMATIC_BACKOFF_MAX_MS: number;
+    readonly VERSION: "2.0.0";
+};
+/**
+ * Merge a caller-supplied TrillboardsConfig with the defaults,
+ * returning a fully-resolved configuration object with no
+ * optional gaps.
+ *
+ * Throws if `deviceId` is empty or whitespace-only.
+ * Numeric fields are clamped to sensible minimums.
+ */
+declare function resolveConfig(userConfig: TrillboardsConfig): {
+    readonly deviceId: string;
+    readonly apiBase: string;
+    readonly cdnBase: string;
+    readonly waterfall: WaterfallMode;
+    readonly autoStart: boolean;
+    readonly refreshInterval: number;
+    readonly heartbeatInterval: number;
+    readonly defaultImageDuration: number;
+    readonly defaultAdInterval: number;
+    readonly programmaticTimeout: number;
+    readonly programmaticMinInterval: number;
+    readonly programmaticRetry: number;
+    readonly programmaticBackoffMax: number;
+    readonly cacheSize: number;
+};
+
+/**
+ * The full internal state held by the SDK engine.
+ * This is NOT exposed to consumers — they receive the
+ * trimmed-down `TrillboardsState` via `getPublicState()`.
+ */
+interface InternalState {
+    deviceId: string | null;
+    partnerId: string | null;
+    screenId: string | null;
+    ads: AdItem[];
+    currentAdIndex: number;
+    isPlaying: boolean;
+    isPaused: boolean;
+    isOffline: boolean;
+    settings: Record<string, unknown>;
+    programmatic: ProgrammaticSettings | null;
+    programmaticPlaying: boolean;
+    prefetchedReady: boolean;
+    waterfallMode: WaterfallMode;
+    autoStart: boolean;
+    container: HTMLElement | null;
+    adTimer: ReturnType<typeof setTimeout> | null;
+    refreshTimer: ReturnType<typeof setInterval> | null;
+    heartbeatTimer: ReturnType<typeof setInterval> | null;
+    programmaticRetryTimer: ReturnType<typeof setTimeout> | null;
+    programmaticRetryActive: boolean;
+    programmaticRetryCount: number;
+    programmaticLastError: string | null;
+    initialized: boolean;
+    screenOrientation: string | null;
+    screenDimensions: ScreenDimensions | null;
+    etag: string | null;
+}
+/**
+ * Default public state used by React components and the IIFE
+ * entry point before the SDK is initialized.
+ */
+declare const DEFAULT_PUBLIC_STATE: TrillboardsState;
+/**
+ * Create a fresh internal state object with safe defaults.
+ * Called once during SDK initialisation.
+ */
+declare function createInitialState(): InternalState;
+/**
+ * Project the internal state into a safe, read-only snapshot
+ * that can be handed to consumers and event listeners.
+ */
+declare function getPublicState(internal: InternalState): TrillboardsState;
+
+/**
+ * Per-source failure tracking to avoid hammering broken demand
+ * sources. Each source independently transitions through three
+ * states:
+ *
+ *   CLOSED  →  failures < maxFailures  →  requests pass through
+ *   OPEN    →  failures >= maxFailures →  requests blocked until openDurationMs elapses
+ *   HALF-OPEN → openDurationMs elapsed →  one request allowed; success resets, failure re-opens
+ */
+declare class CircuitBreaker {
+    private sources;
+    readonly maxFailures: number;
+    readonly openDurationMs: number;
+    constructor(maxFailures?: number, openDurationMs?: number);
+    /**
+     * Record a successful request for a source, resetting its
+     * failure counter and clearing any open-circuit timer.
+     */
+    recordSuccess(sourceName: string): void;
+    /**
+     * Record a failed request for a source. When consecutive
+     * failures reach `maxFailures`, the circuit opens for
+     * `openDurationMs` milliseconds.
+     */
+    recordFailure(sourceName: string): void;
+    /**
+     * Check whether a source is available for requests.
+     *
+     * Returns `true` when:
+     *  - The source has never been tracked (unknown = available)
+     *  - Consecutive failures are below the threshold (CLOSED)
+     *  - The open-circuit timer has elapsed (HALF-OPEN — allow a probe)
+     */
+    isAvailable(sourceName: string): boolean;
+    /**
+     * Return the raw circuit breaker state for a source.
+     * Returns a zeroed-out state for unknown sources.
+     */
+    getState(sourceName: string): CircuitBreakerState;
+    /**
+     * Clear all tracked source state.
+     */
+    reset(): void;
+}
+
+/**
+ * Lightweight counters for ad-request outcomes.
+ *
+ * Every call to `play()` on the programmatic player should call
+ * `recordRequest()`. Depending on the outcome, one of
+ * `recordFill()`, `recordNoFill()`, `recordTimeout()`, or
+ * `recordError()` is then called. The snapshot exposes rates
+ * (0-1, rounded to 4 decimal places) that can be sent to the
+ * server for monitoring.
+ */
+declare class Telemetry {
+    private totalRequests;
+    private fills;
+    private noFills;
+    private timeouts;
+    private errors;
+    /** Count a new ad request. */
+    recordRequest(): void;
+    /** Count a successful fill (ad loaded and ready to play). */
+    recordFill(): void;
+    /** Count a request that returned no ad (no fill). */
+    recordNoFill(): void;
+    /** Count a request that timed out before a response arrived. */
+    recordTimeout(): void;
+    /** Count a request that failed with an error (not a timeout). */
+    recordError(): void;
+    /** Ratio of fills to total requests (0-1). */
+    getFillRate(): number;
+    /** Ratio of no-fills to total requests (0-1). */
+    getNoFillRate(): number;
+    /** Ratio of timeouts to total requests (0-1). */
+    getTimeoutRate(): number;
+    /** Ratio of errors to total requests (0-1). */
+    getErrorRate(): number;
+    /**
+     * Return a snapshot object suitable for serialization.
+     * Rates are rounded to four decimal places.
+     */
+    getSnapshot(): TelemetrySnapshot;
+    /** Reset all counters to zero. */
+    reset(): void;
+}
+
+interface WaterfallResult {
+    source: VastSource;
+    vastUrl: string;
+}
+/**
+ * Manages iterating through waterfall demand sources in priority
+ * order, skipping circuit-broken sources. Lower priority numbers
+ * are tried first. Equal-priority sources are randomized to
+ * distribute load evenly.
+ */
+declare class WaterfallEngine {
+    private circuitBreaker;
+    constructor(circuitBreaker: CircuitBreaker);
+    /**
+     * Get the next available VAST source from the waterfall.
+     * Sources are sorted by priority (lower = higher priority),
+     * with a random tiebreaker for equal priorities.
+     * Circuit-broken sources are skipped.
+     *
+     * If all sources are circuit-broken, returns `null` to let
+     * the caller handle retry scheduling rather than bypassing
+     * the circuit breaker.
+     */
+    getNextSource(sources: VastSource[]): WaterfallResult | null;
+    /**
+     * Get all available sources in priority order (for parallel bidding).
+     * Only returns sources that are not circuit-broken.
+     * Equal-priority sources are randomized for load distribution.
+     */
+    getAvailableSources(sources: VastSource[]): WaterfallResult[];
+    /** Record a successful ad fill for a source. */
+    recordSuccess(sourceName: string): void;
+    /** Record a failed request for a source. */
+    recordFailure(sourceName: string): void;
+}
+
+/**
+ * Low-level HTTP client for the Trillboards Partner API.
+ *
+ * Each method maps 1-to-1 to an endpoint:
+ *  - `fetchAds`                — `GET  /device/:id/ads`
+ *  - `reportImpression`        — `GET  /impression`
+ *  - `sendHeartbeat`           — `POST /device/:id/heartbeat`
+ *  - `reportProgrammaticEvent` — `POST /programmatic-event`
+ */
+declare class ApiClient {
+    private apiBase;
+    private container;
+    constructor(apiBase?: string);
+    /** Bind an optional container element for slot-size measurement. */
+    setContainer(container: HTMLElement | null): void;
+    /**
+     * Fetch the current ad roster for a device.
+     *
+     * Supports conditional requests via `ETag` / `If-None-Match` —
+     * when the server returns 304 the caller receives the previous
+     * ad list untouched (indicated by `notModified: true`).
+     *
+     * The request is aborted after 10 seconds.
+     */
+    fetchAds(deviceId: string, etag?: string | null): Promise<FetchAdsResult>;
+    /**
+     * Fire an impression pixel.
+     *
+     * Uses a GET request with query-string parameters so the call
+     * survives `navigator.sendBeacon`-like fallback patterns and
+     * can be retried transparently on network failure.
+     *
+     * Returns `true` if the server acknowledged the impression.
+     */
+    reportImpression(impression: {
+        adid: string;
+        impid: string;
+        did: string;
+        aid: string;
+        duration: number;
+        completed: boolean;
+    }): Promise<boolean>;
+    /**
+     * Ping the heartbeat endpoint to signal this device is alive.
+     * Returns `true` on 2xx, `false` on any error.
+     */
+    sendHeartbeat(deviceId: string, screenId: string | null): Promise<boolean>;
+    /**
+     * Report a programmatic lifecycle event (VAST fill, timeout,
+     * error, etc.) to the analytics backend.
+     */
+    reportProgrammaticEvent(event: {
+        screenId: string;
+        deviceId: string;
+        eventType: string;
+        vastSource?: string;
+        variantName?: string;
+        errorCode?: number;
+        errorMessage?: string;
+        duration?: number;
+        telemetry?: Record<string, number>;
+    }): Promise<boolean>;
+}
+
+export { type AdItem, ApiClient, type AuctionWinner, type BridgeConfig, type BridgePayload, type BridgeType, CircuitBreaker, type CircuitBreakerState, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, type EventMap, type FetchAdsResult, type ImpressionData, type PlayerTruth, type ProgrammaticSettings, SDK_VERSION, type ScreenDimensions, Telemetry, type TelemetrySnapshot, TrillboardsAds, type TrillboardsConfig, type TrillboardsState, type VastSource, WaterfallEngine, type WaterfallMode, createInitialState, getPublicState, resolveConfig };