@trillboards/ads-sdk 2.0.0

package/dist/react.d.mts

@@ -0,0 +1,239 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+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 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 BridgeConfig {
+    send: (event: string, data: unknown) => void;
+    receive?: (callback: (command: unknown) => void) => void;
+    events?: string[];
+    name?: string;
+}
+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;
+}
+
+interface TrillboardsContextValue {
+    sdk: TrillboardsAds | null;
+    state: TrillboardsState;
+    isReady: boolean;
+    error: string | null;
+}
+interface TrillboardsProviderProps {
+    config: TrillboardsConfig;
+    children: React.ReactNode;
+}
+declare function TrillboardsProvider({ config, children }: TrillboardsProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTrillboardsContext(): TrillboardsContextValue;
+
+interface UseTrillboardsAdsReturn {
+    isReady: boolean;
+    error: string | null;
+    state: TrillboardsState;
+    ads: AdItem[];
+    hasPrefetchedAd: boolean;
+    show: () => void;
+    hide: () => void;
+    skipAd: () => void;
+    refresh: () => Promise<void>;
+    prefetchNextAd: () => Promise<void>;
+}
+declare function useTrillboardsAds(): UseTrillboardsAdsReturn;
+
+declare function useAdEvents<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+
+interface TrillboardsAdSlotProps {
+    style?: React.CSSProperties;
+    className?: string;
+    onAdStarted?: (data: EventMap['ad_started']) => void;
+    onAdEnded?: (data: EventMap['ad_ended']) => void;
+    onAdError?: (data: EventMap['ad_error']) => void;
+}
+declare function TrillboardsAdSlot({ style, className, onAdStarted, onAdEnded, onAdError, }: TrillboardsAdSlotProps): react_jsx_runtime.JSX.Element;
+
+export { type AdItem, type EventMap, TrillboardsAdSlot, type TrillboardsAdSlotProps, type TrillboardsConfig, TrillboardsProvider, type TrillboardsProviderProps, type TrillboardsState, type UseTrillboardsAdsReturn, type WaterfallMode, useAdEvents, useTrillboardsAds, useTrillboardsContext };

package/dist/react.d.ts

@@ -0,0 +1,239 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+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 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 BridgeConfig {
+    send: (event: string, data: unknown) => void;
+    receive?: (callback: (command: unknown) => void) => void;
+    events?: string[];
+    name?: string;
+}
+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;
+}
+
+interface TrillboardsContextValue {
+    sdk: TrillboardsAds | null;
+    state: TrillboardsState;
+    isReady: boolean;
+    error: string | null;
+}
+interface TrillboardsProviderProps {
+    config: TrillboardsConfig;
+    children: React.ReactNode;
+}
+declare function TrillboardsProvider({ config, children }: TrillboardsProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTrillboardsContext(): TrillboardsContextValue;
+
+interface UseTrillboardsAdsReturn {
+    isReady: boolean;
+    error: string | null;
+    state: TrillboardsState;
+    ads: AdItem[];
+    hasPrefetchedAd: boolean;
+    show: () => void;
+    hide: () => void;
+    skipAd: () => void;
+    refresh: () => Promise<void>;
+    prefetchNextAd: () => Promise<void>;
+}
+declare function useTrillboardsAds(): UseTrillboardsAdsReturn;
+
+declare function useAdEvents<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+
+interface TrillboardsAdSlotProps {
+    style?: React.CSSProperties;
+    className?: string;
+    onAdStarted?: (data: EventMap['ad_started']) => void;
+    onAdEnded?: (data: EventMap['ad_ended']) => void;
+    onAdError?: (data: EventMap['ad_error']) => void;
+}
+declare function TrillboardsAdSlot({ style, className, onAdStarted, onAdEnded, onAdError, }: TrillboardsAdSlotProps): react_jsx_runtime.JSX.Element;
+
+export { type AdItem, type EventMap, TrillboardsAdSlot, type TrillboardsAdSlotProps, type TrillboardsConfig, TrillboardsProvider, type TrillboardsProviderProps, type TrillboardsState, type UseTrillboardsAdsReturn, type WaterfallMode, useAdEvents, useTrillboardsAds, useTrillboardsContext };