adgent-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,874 @@
+/** Ad element - can be inline or wrapper */
+export declare interface Ad {
+    id: string;
+    sequence?: number;
+    adSystem?: AdSystem;
+    adTitle?: string;
+    impressions: Impression[];
+    creatives: Creative[];
+    errors: string[];
+    /** Present if this is a wrapper ad */
+    wrapper?: Wrapper;
+    /** Present if this is an inline ad */
+    inLine?: InLine;
+}
+
+/** Error structure */
+export declare interface AdError {
+    code: VASTErrorCode | number;
+    message: string;
+    details?: string;
+    recoverable: boolean;
+}
+
+/**
+ * Ad Player with fault-tolerant playback for Smart TV platforms
+ *
+ * Features:
+ * - "Nuclear Mute" strategy: muted + playsinline + autoplay attributes
+ * - Soft-fail autoplay: catches play() rejection, shows interactive overlay
+ * - Focus management: captures remote keys during ad playback
+ */
+declare class AdPlayer {
+    private readonly config;
+    private readonly platform;
+    private readonly parser;
+    private videoElement;
+    private overlayElement;
+    private skipButtonElement;
+    private tracker;
+    private state;
+    private ads;
+    private listeners;
+    private quartilesFired;
+    private boundKeyHandler;
+    private focusTrap;
+    constructor(config: AdPlayerConfig);
+    /**
+     * Initialize the SDK: fetch VAST, create video element, attempt autoplay
+     */
+    init(): Promise<void>;
+    /**
+     * Get the first linear creative from parsed ads
+     */
+    private getFirstLinearCreative;
+    /**
+     * Create video element with "Nuclear Mute" strategy
+     * Applies muted, playsinline, autoplay for maximum TV compatibility
+     */
+    private createVideoElement;
+    /**
+     * Attempt autoplay with soft-fail handling
+     * If play() rejects (common on TVs), show interactive overlay
+     */
+    private attemptAutoplay;
+    /**
+     * Show interactive overlay for manual ad start (autoplay fallback)
+     */
+    private showStartOverlay;
+    /**
+     * Handle start button click (from overlay)
+     */
+    private onStartClick;
+    /**
+     * Remove the start overlay
+     */
+    private removeOverlay;
+    /**
+     * Handle successful playback start
+     */
+    private handlePlaybackStart;
+    /**
+     * Handle time updates for progress tracking
+     */
+    private handleTimeUpdate;
+    /**
+     * Calculate current quartile (0-4)
+     */
+    private calculateQuartile;
+    /**
+     * Fire quartile tracking events
+     */
+    private fireQuartileEvents;
+    /**
+     * Set up skip button
+     */
+    private setupSkipButton;
+    /**
+     * Update skip countdown
+     */
+    private updateSkipCountdown;
+    /**
+     * Skip the ad
+     */
+    skip(): void;
+    /**
+     * Handle ad completion
+     */
+    private handleComplete;
+    /**
+     * Handle errors with recovery attempt or callback
+     */
+    private handleError;
+    /**
+     * Set up focus management to capture remote keys
+     */
+    private setupFocusManagement;
+    /**
+     * Handle key actions from remote control
+     */
+    private handleKeyAction;
+    /**
+     * Unmute video (call after playback starts if needed)
+     */
+    unmute(): void;
+    /**
+     * Mute video
+     */
+    mute(): void;
+    /**
+     * Add event listener
+     */
+    on(listener: AdPlayerEventListener): () => void;
+    /**
+     * Get current state
+     */
+    getState(): AdPlayerState;
+    /**
+     * Clean up all resources
+     */
+    destroy(): void;
+    /**
+     * Update internal state
+     */
+    private updateState;
+    /**
+     * Emit event to listeners
+     */
+    private emit;
+    /**
+     * Create error object
+     */
+    private createError;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+export { AdPlayer }
+export { AdPlayer as AdgentSDK }
+
+/** SDK initialization configuration */
+export declare interface AdPlayerConfig {
+    /** Container element to render ad player into */
+    container: HTMLElement;
+    /** VAST tag URL to fetch */
+    vastUrl: string;
+    /** Target bitrate in kbps (default: 2500 for ~1080p) */
+    targetBitrate?: number;
+    /** Maximum VAST wrapper depth (default: 5) */
+    maxWrapperDepth?: number;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom skip button text */
+    skipButtonText?: string;
+    /** Skip offset override in seconds (0 = no skip allowed) */
+    skipOffset?: number;
+    /** Callback when ad playback completes */
+    onComplete?: () => void;
+    /** Callback when an error occurs */
+    onError?: (error: AdError) => void;
+    /** Callback when ad starts playing */
+    onStart?: () => void;
+    /** Callback for progress updates */
+    onProgress?: (progress: AdProgress) => void;
+    /** Callback when ad is skipped */
+    onSkip?: () => void;
+    /** Callback when user clicks the ad */
+    onClick?: (clickThroughUrl: string) => void;
+    /** Callback when ad is paused */
+    onPause?: () => void;
+    /** Callback when ad resumes */
+    onResume?: () => void;
+    /** Custom "Start Ad" overlay UI (for autoplay fallback) */
+    customStartOverlay?: HTMLElement;
+}
+
+/** Events emitted by the player */
+export declare type AdPlayerEvent = {
+    type: 'loaded';
+} | {
+    type: 'start';
+} | {
+    type: 'progress';
+    data: AdProgress;
+} | {
+    type: 'quartile';
+    data: {
+        quartile: TrackingEventType;
+    };
+} | {
+    type: 'complete';
+} | {
+    type: 'skip';
+} | {
+    type: 'click';
+    data: {
+        url: string;
+    };
+} | {
+    type: 'pause';
+} | {
+    type: 'resume';
+} | {
+    type: 'mute';
+} | {
+    type: 'unmute';
+} | {
+    type: 'error';
+    data: AdError;
+} | {
+    type: 'destroy';
+};
+
+/** Event listener callback */
+export declare type AdPlayerEventListener = (event: AdPlayerEvent) => void;
+
+/** Current player state */
+export declare interface AdPlayerState {
+    /** Current playback status */
+    status: PlaybackStatus;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Whether ad is muted */
+    muted: boolean;
+    /** Current volume (0-1) */
+    volume: number;
+    /** Whether skip is available */
+    canSkip: boolean;
+    /** Seconds until skip is available */
+    skipCountdown: number;
+    /** Selected media file being played */
+    mediaFile: MediaFile | null;
+    /** Last error if any */
+    error: AdError | null;
+}
+
+/** Progress event data */
+export declare interface AdProgress {
+    currentTime: number;
+    duration: number;
+    percentage: number;
+    quartile: 0 | 1 | 2 | 3 | 4;
+}
+
+/** Ad system information */
+declare interface AdSystem {
+    name: string;
+    version?: string;
+}
+
+/**
+ * Fire-and-forget pixel tracker for VAST events
+ */
+export declare class AdTracker {
+    private readonly config;
+    private readonly trackingEvents;
+    private firedEvents;
+    private macroContext;
+    constructor(events?: TrackingEvent[], config?: TrackerConfig);
+    /**
+     * Group tracking events by their event type
+     */
+    private groupEventsByType;
+    /**
+     * Update macro context for URL replacement
+     */
+    updateMacroContext(context: Partial<MacroContext>): void;
+    /**
+     * Track a specific event type
+     * @param eventType - The VAST event type to track
+     * @param once - Only fire once per event type (default: true)
+     */
+    track(eventType: TrackingEventType, once?: boolean): void;
+    /**
+     * Fire a single tracking pixel (fire-and-forget)
+     * Uses sendBeacon when available, falls back to fetch with keepalive
+     */
+    firePixel(url: string): void;
+    /**
+     * Image beacon fallback
+     */
+    private fireImageBeacon;
+    /**
+     * Fire impression pixels
+     * @param impressionUrls - Array of impression URLs
+     */
+    fireImpressions(impressionUrls: string[]): void;
+    /**
+     * Fire error tracking with error code
+     * @param errorUrls - Array of error tracking URLs
+     * @param errorCode - VAST error code
+     */
+    fireError(errorUrls: string[], errorCode: number): void;
+    /**
+     * Reset fired events (for replay scenarios)
+     */
+    reset(): void;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/** Content category */
+declare interface Category {
+    authority?: string;
+    value: string;
+}
+
+export declare interface ClickThrough {
+    id?: string;
+    url: string;
+}
+
+declare interface ClickTracking {
+    id?: string;
+    url: string;
+}
+
+/** Companion ad (banner alongside video) */
+export declare interface CompanionAd {
+    id?: string;
+    width: number;
+    height: number;
+    staticResource?: string;
+    iFrameResource?: string;
+    htmlResource?: string;
+    companionClickThrough?: string;
+    trackingEvents: TrackingEvent[];
+}
+
+/** Creative element containing Linear/NonLinear/Companion ads */
+export declare interface Creative {
+    id?: string;
+    sequence?: number;
+    adId?: string;
+    linear?: Linear;
+    nonLinearAds?: NonLinearAd[];
+    companionAds?: CompanionAd[];
+}
+
+declare interface CustomClick {
+    id?: string;
+    url: string;
+}
+
+/** Default key codes (varies by platform) */
+export declare const DEFAULT_KEY_CODES: Record<Platform, PlatformKeyMap>;
+
+/** Device info */
+export declare interface DeviceInfo {
+    platform: Platform;
+    model?: string;
+    manufacturer?: string;
+    osVersion?: string;
+    firmwareVersion?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    devicePixelRatio?: number;
+}
+
+/**
+ * Get or create the platform adapter singleton
+ */
+export declare function getPlatformAdapter(): PlatformAdapter;
+
+/** Icon overlay (e.g., AdChoices) */
+export declare interface Icon {
+    program?: string;
+    width: number;
+    height: number;
+    xPosition: string | number;
+    yPosition: string | number;
+    duration?: number;
+    offset?: number;
+    staticResource?: string;
+    iFrameResource?: string;
+    htmlResource?: string;
+    iconClicks?: IconClicks;
+}
+
+declare interface IconClicks {
+    iconClickThrough?: string;
+    iconClickTracking?: string[];
+}
+
+/** Impression pixel */
+export declare interface Impression {
+    id?: string;
+    url: string;
+}
+
+/** Inline ad content */
+export declare interface InLine {
+    adTitle: string;
+    description?: string;
+    advertiser?: string;
+    pricing?: Pricing;
+    survey?: string;
+    category?: Category[];
+    creatives: Creative[];
+}
+
+/** Platform adapter interface */
+export declare interface IPlatformAdapter {
+    /** Current detected platform */
+    readonly platform: Platform;
+    /** Platform capabilities */
+    readonly capabilities: PlatformCapabilities;
+    /** Device information */
+    readonly deviceInfo: DeviceInfo;
+    /**
+     * Normalize a raw key code to a KeyAction
+     * @param keyCode - Raw keyboard/remote key code
+     */
+    normalizeKeyCode(keyCode: number): KeyAction | null;
+    /**
+     * Get platform-specific key codes for an action
+     * @param action - The key action to get codes for
+     */
+    getKeyCodesForAction(action: KeyAction): number[];
+    /**
+     * Check if a specific codec is supported
+     * @param codec - MIME type with codec (e.g., 'video/mp4; codecs="hvc1"')
+     */
+    isCodecSupported(codec: string): boolean;
+}
+
+/** Remote control key actions */
+export declare enum KeyAction {
+    Enter = "enter",
+    Back = "back",
+    Left = "left",
+    Right = "right",
+    Up = "up",
+    Down = "down",
+    Play = "play",
+    Pause = "pause",
+    PlayPause = "playPause",
+    Stop = "stop",
+    FastForward = "fastForward",
+    Rewind = "rewind",
+    Menu = "menu",
+    Info = "info",
+    Red = "red",
+    Green = "green",
+    Yellow = "yellow",
+    Blue = "blue",
+    ChannelUp = "channelUp",
+    ChannelDown = "channelDown",
+    VolumeUp = "volumeUp",
+    VolumeDown = "volumeDown",
+    Mute = "mute"
+}
+
+/** Linear (video) ad */
+export declare interface Linear {
+    duration: number;
+    skipOffset?: number;
+    mediaFiles: MediaFile[];
+    trackingEvents: TrackingEvent[];
+    videoClicks?: VideoClicks;
+    adParameters?: string;
+    icons?: Icon[];
+}
+
+/** Macro replacement context */
+export declare interface MacroContext {
+    assetUri?: string;
+    contentPlayhead?: number;
+    adPlayhead?: number;
+    errorCode?: number;
+    breakPosition?: number;
+    adType?: string;
+}
+
+/** Video file reference */
+export declare interface MediaFile {
+    id?: string;
+    url: string;
+    delivery: 'progressive' | 'streaming';
+    type: string;
+    width: number;
+    height: number;
+    bitrate?: number;
+    minBitrate?: number;
+    maxBitrate?: number;
+    scalable?: boolean;
+    maintainAspectRatio?: boolean;
+    codec?: string;
+    apiFramework?: string;
+}
+
+/** NonLinear ad (overlay) */
+export declare interface NonLinearAd {
+    id?: string;
+    width: number;
+    height: number;
+    minSuggestedDuration?: number;
+    staticResource?: string;
+    iFrameResource?: string;
+    htmlResource?: string;
+    nonLinearClickThrough?: string;
+    trackingEvents: TrackingEvent[];
+}
+
+/** Parse result */
+declare interface ParseResult {
+    success: boolean;
+    response?: VASTResponse;
+    error?: {
+        code: VASTErrorCode;
+        message: string;
+    };
+}
+
+/**
+ * Platform Detection Types
+ * For Smart TV web runtimes (WebOS, Tizen, Vidaa, WhaleOS) and streaming devices
+ */
+/** Supported Smart TV platforms */
+export declare enum Platform {
+    WebOS = "webos",
+    Tizen = "tizen",
+    Vidaa = "vidaa",
+    WhaleOS = "whaleos",
+    FireTV = "firetv",
+    Roku = "roku",
+    Xbox = "xbox",
+    PlayStation = "playstation",
+    AndroidTV = "androidtv",
+    Vizio = "vizio",
+    Generic = "generic"
+}
+
+/** Platform detection patterns */
+export declare const PLATFORM_DETECTION_PATTERNS: Record<Platform, RegExp[]>;
+
+/**
+ * Platform detection and key code normalization for Smart TV runtimes
+ */
+export declare class PlatformAdapter implements IPlatformAdapter {
+    readonly platform: Platform;
+    readonly capabilities: PlatformCapabilities;
+    readonly deviceInfo: DeviceInfo;
+    private readonly keyMap;
+    private readonly reverseKeyMap;
+    constructor();
+    /**
+     * Detect the current Smart TV platform using userAgent and global objects
+     */
+    private detectPlatform;
+    /**
+     * Detect platform capabilities
+     */
+    private detectCapabilities;
+    /**
+     * Detect device information
+     */
+    private detectDeviceInfo;
+    /**
+     * Detect maximum supported resolution
+     */
+    private detectMaxResolution;
+    /**
+     * Build reverse mapping from KeyAction to key codes
+     */
+    private buildReverseKeyMap;
+    /**
+     * Normalize a raw key code to a KeyAction
+     * @param keyCode - Raw keyboard/remote key code
+     * @returns KeyAction or null if not mapped
+     */
+    normalizeKeyCode(keyCode: number): KeyAction | null;
+    /**
+     * Get all key codes that map to a specific action
+     * @param action - The key action
+     * @returns Array of key codes
+     */
+    getKeyCodesForAction(action: KeyAction): number[];
+    /**
+     * Check if a specific codec is supported
+     * @param codec - MIME type with codec string
+     * @returns true if codec is supported
+     */
+    isCodecSupported(codec: string): boolean;
+    /**
+     * Register Tizen-specific key handlers
+     * Must be called for Tizen apps to receive media keys
+     */
+    registerTizenKeys(): void;
+    /**
+     * Register WebOS-specific key handlers
+     */
+    registerWebOSKeys(): void;
+    /**
+     * Get platform-specific video element attributes
+     * @returns Object of attributes to set on video element
+     */
+    getVideoAttributes(): Record<string, string | boolean>;
+    /**
+     * Get recommended video settings for this platform
+     */
+    getRecommendedVideoSettings(): {
+        maxBitrate: number;
+        preferredCodec: string;
+        maxResolution: string;
+    };
+}
+
+/** Platform capability flags */
+export declare interface PlatformCapabilities {
+    /** Supports sendBeacon API */
+    sendBeacon: boolean;
+    /** Supports fetch with keepalive */
+    fetchKeepalive: boolean;
+    /** Requires muted autoplay */
+    mutedAutoplayRequired: boolean;
+    /** Supports fullscreen API */
+    fullscreen: boolean;
+    /** Supports hardware video decode info */
+    hardwareDecodeInfo: boolean;
+    /** Supports HDR playback */
+    hdr: boolean;
+    /** Supports HDR10+ */
+    hdr10Plus: boolean;
+    /** Supports Dolby Vision */
+    dolbyVision: boolean;
+    /** Supports Dolby Atmos */
+    dolbyAtmos: boolean;
+    /** Supports HEVC/H.265 */
+    hevc: boolean;
+    /** Supports VP9 */
+    vp9: boolean;
+    /** Supports AV1 */
+    av1: boolean;
+    /** Maximum supported resolution */
+    maxResolution: '4k' | '1080p' | '720p' | 'unknown';
+    /** Device has touch support */
+    touch: boolean;
+    /** Device has voice control */
+    voice: boolean;
+}
+
+/** Platform-specific key code mapping */
+export declare interface PlatformKeyMap {
+    [keyCode: number]: KeyAction;
+}
+
+/** Playback status enum */
+export declare enum PlaybackStatus {
+    Idle = "idle",
+    Loading = "loading",
+    Ready = "ready",
+    Playing = "playing",
+    Paused = "paused",
+    Completed = "completed",
+    Error = "error",
+    WaitingForInteraction = "waiting_for_interaction"
+}
+
+/** Pricing information */
+declare interface Pricing {
+    model: 'cpm' | 'cpc' | 'cpe' | 'cpv';
+    currency: string;
+    value: number;
+}
+
+/**
+ * Replace all VAST macros in a URL
+ * @param url - URL containing macros
+ * @param context - Values to substitute
+ */
+export declare function replaceMacros(url: string, context?: MacroContext): string;
+
+/** Tracker configuration */
+declare interface TrackerConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Retry failed requests (default: false for fire-and-forget) */
+    retry?: boolean;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+}
+
+/** Tracking event for analytics */
+export declare interface TrackingEvent {
+    event: TrackingEventType;
+    url: string;
+    offset?: number;
+}
+
+/** Supported tracking event types per VAST 4.x */
+export declare type TrackingEventType = 'creativeView' | 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'mute' | 'unmute' | 'pause' | 'resume' | 'rewind' | 'skip' | 'playerExpand' | 'playerCollapse' | 'progress' | 'closeLinear' | 'loaded' | 'impression' | 'error';
+
+/** Error codes per VAST spec */
+export declare enum VASTErrorCode {
+    XML_PARSING_ERROR = 100,
+    VAST_SCHEMA_VALIDATION_ERROR = 101,
+    VAST_VERSION_NOT_SUPPORTED = 102,
+    GENERAL_WRAPPER_ERROR = 300,
+    WRAPPER_TIMEOUT = 301,
+    WRAPPER_LIMIT_REACHED = 302,
+    NO_VAST_RESPONSE = 303,
+    GENERAL_LINEAR_ERROR = 400,
+    FILE_NOT_FOUND = 401,
+    MEDIA_TIMEOUT = 402,
+    MEDIA_NOT_SUPPORTED = 403,
+    GENERAL_COMPANION_ERROR = 600,
+    UNDEFINED_ERROR = 900
+}
+
+/**
+ * Macro Replacement Utilities
+ * Handles VAST macro substitution for tracking URLs
+ */
+/** Supported VAST macros */
+export declare type VastMacro = '[TIMESTAMP]' | '[CACHEBUSTING]' | '[ASSETURI]' | '[CONTENTPLAYHEAD]' | '[ERRORCODE]' | '[BREAKPOSITION]' | '[ADPLAYHEAD]' | '[ADTYPE]';
+
+/**
+ * VAST XML Parser with wrapper resolution
+ */
+export declare class VASTParser {
+    private readonly config;
+    private readonly xmlParser;
+    constructor(config?: VASTParserConfig);
+    /**
+     * Parse a VAST URL and resolve all wrappers
+     * @param vastUrl - URL to the VAST document
+     */
+    parse(vastUrl: string): Promise<ParseResult>;
+    /**
+     * Fetch and parse VAST document with wrapper resolution
+     */
+    private fetchAndParse;
+    /**
+     * Resolve a wrapper ad by fetching the nested VAST
+     */
+    private resolveWrapper;
+    /**
+     * Merge tracking events from wrapper into nested ad
+     */
+    private mergeWrapperTracking;
+    /**
+     * Extract tracking events from wrapper creatives
+     */
+    private getWrapperTrackingEvents;
+    /**
+     * Fetch URL with timeout
+     */
+    private fetchWithTimeout;
+    /**
+     * Parse raw VAST XML into structured response
+     */
+    private parseXml;
+    /**
+     * Parse Ad elements
+     */
+    private parseAds;
+    /**
+     * Parse a single Ad element
+     */
+    private parseAd;
+    /**
+     * Parse Impression elements
+     */
+    private parseImpressions;
+    /**
+     * Parse Creative elements
+     */
+    private parseCreatives;
+    /**
+     * Parse Linear element
+     */
+    private parseLinear;
+    /**
+     * Parse MediaFile elements
+     */
+    private parseMediaFiles;
+    /**
+     * Parse Tracking elements
+     */
+    private parseTrackingEvents;
+    /**
+     * Parse Error elements
+     */
+    private parseErrors;
+    /**
+     * Parse duration string (HH:MM:SS or seconds) to seconds
+     */
+    private parseDuration;
+    /**
+     * Select the best media file based on target bitrate
+     * Prefers 1080p/720p over 4K for TV compatibility
+     */
+    selectBestMediaFile(mediaFiles: MediaFile[], targetBitrate?: number): MediaFile | null;
+    /**
+     * Aggregate all tracking events from parsed ads
+     */
+    aggregateTrackingEvents(ads: Ad[]): TrackingEvent[];
+    /**
+     * Get all impression URLs from parsed ads
+     */
+    aggregateImpressions(ads: Ad[]): string[];
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/** Parser configuration */
+declare interface VASTParserConfig {
+    /** Maximum wrapper depth (default: 5) */
+    maxWrapperDepth?: number;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom fetch implementation */
+    fetchFn?: typeof fetch;
+}
+
+/**
+ * VAST 4.x Type Definitions
+ * Based on IAB VAST (Video Ad Serving Template) 4.x Specification
+ * @see https://iabtechlab.com/standards/vast/
+ */
+/** Root VAST response structure */
+export declare interface VASTResponse {
+    version: string;
+    ads: Ad[];
+    errors: string[];
+}
+
+/** Video click tracking */
+export declare interface VideoClicks {
+    clickThrough?: ClickThrough;
+    clickTracking?: ClickTracking[];
+    customClick?: CustomClick[];
+}
+
+/** Wrapper ad - points to another VAST */
+export declare interface Wrapper {
+    vastAdTagURI: string;
+    followAdditionalWrappers?: boolean;
+    allowMultipleAds?: boolean;
+    fallbackOnNoAd?: boolean;
+}
+
+export { }