@dolby-optiview/ads-sdk-core 1.2.1 → 1.4.0

package/dist/OptiViewAds.d.ts

@@ -41,10 +41,8 @@ export declare class OptiViewAds {
     static get version(): string;
     private player;
     private readonly liveStartPushback;
-    /** Releases the scheduler's reload guard after a content error — see onContentError. */
-    private contentErrorReloadGuard;
-    /** How long a content error brackets scheduler position samples as reload noise. */
-    private readonly CONTENT_ERROR_RELOAD_GUARD_MS;
+    /** A content error brackets scheduler position samples as reload noise for 5s — see onContentError. */
+    private readonly contentErrorReloadGuard;
     private manifestService?;
     private breakScheduler?;
     private adPlayerController?;
@@ -66,6 +64,7 @@ export declare class OptiViewAds {
     private sessionStarter;
     private readonly adBreakStatusTracker;
     private breakTransitionTimer?;
+    private breakChainRecorder?;
     private readonly onContentSeeked;
     private readonly onContentWaiting;
     private readonly onContentPlaying;
@@ -78,6 +77,8 @@ export declare class OptiViewAds {
     /** Break ids already reported as newly seen on DA-MANIFEST-POLLED (see notedManifestBreakIds). */
     private seenManifestBreakIds;
     private readonly onTimedMetadata;
+    private readonly externalPlayback;
+    private ssbSwitch;
     constructor(config: OptiViewAdsConfig);
     /** SSAI-mode construction: no manifest service, break scheduler, or ad-player overlay. */
     private initSsai;

package/dist/OptiViewAds.js

@@ -1 +1 @@
-import{DEFAULT_MODE as e,DEFAULT_AD_PRELOAD_MODE as t,DEFAULT_AD_BREAK_CONTENT_RECOVERY as s,DEFAULT_AD_INSERTION_MODE as r,DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC as i,DEFAULT_DOUBLE_BOX_AUDIO as a,resolveChaining as o,resolveTuneIn as n,resolveBreakWarnings as d,resolvePdtGraceSeconds as l}from"./types/OptiViewAdsConfig";import{SsaiController as h}from"./services/SsaiController";import{resolvePreloadMode as c}from"./services/detectPreloadMode";import{resolveContentRecovery as u}from"./services/detectContentRecovery";import{emitResolvedModeDiagnostics as m}from"./services/resolvedModeDiagnostics";import{isSingleSurfaceWebDevice as p,resolveInsertionMode as k}from"./services/detectInsertionMode";import{ManifestService as g}from"./services/ManifestService";import{BreakScheduler as f,systemClock as y}from"./services/BreakScheduler";import{MetadataCueTracker as S}from"./services/MetadataCueTracker";import{armBreakFromPresentedCue as v,diagnoseAnvatoCueObserved as C,notedManifestBreakIds as A,wireCueResume as b}from"./services/anvatoCueRuntime";import{AdPlayerController as P}from"./services/AdPlayerController";import{effectiveFormat as T}from"./services/pictureInPicture";import{resolveBreakFormat as B}from"./services/AdBreakSequencer";import{connectPauseAd as w}from"./services/adPlayer/connectPauseAd";import{BreakTransitionTimer as I}from"./services/BreakTransitionTimer";import{LensReporter as R}from"./services/LensReporter";import{CmcdAdReporter as D}from"./services/CmcdAdReporter";import{DiagnosticBuffer as E}from"./diagnostics/DiagnosticBuffer";import{recordEventTimeline as O}from"./diagnostics/recordEventTimeline";import{DIAGNOSTIC_CODES as M}from"./diagnostics/errorCodes";import{SDK_VERSION as x}from"./generated/version";import{playbackErrorContext as L}from"./diagnostics/playbackErrorContext";import{debugLog as V}from"./diagnostics/debugLog";import{AdBreakStatusTracker as G}from"./session/AdBreakStatusTracker";import{BreakLifecycle as H}from"./session/BreakLifecycle";import{SessionStarter as F}from"./session/SessionStarter";import{SessionState as q}from"./session/SessionState";import{LiveStartPushbackController as N}from"./services/LiveStartPushbackController";import{buildDiagnosticReport as K}from"./services/diagnosticReport";import{toPlaybackError as $}from"./services/toPlaybackError";import{readExternalVendorConfiguration as _}from"./services/externalVendorConfigurationGetter";import{createExternalVendorConfigurationTracker as U}from"./services/ExternalVendorConfigurationTracker";export class OptiViewAds{static get version(){return x}constructor(h){if(this.contentErrorReloadGuard=null,this.CONTENT_ERROR_RELOAD_GUARD_MS=5e3,this.eventHandlers=new Map,this.diagnosticHandlers=new Set,this.destroyed=!1,this.externalVendorConfigurationTracker=U(e=>this.emit("externalvendorconfigurationchange",e)),this.continueContentDuringBreak=!1,this.state=new q,this.metadataCueTracker=null,this.anvatoObservedLogged=new Set,this.seenManifestBreakIds=new Set,this.player=h.player,this.liveStartPushback=new N(this.player,h.liveStartPushback,{blocked:()=>!this.state.sessionActive||this.state.channelSwitchInFlight||!!this.adPlayerController?.isAdPlaying()||!!this.state.heldImmediatePreRollId,setSeeking:e=>this.breakScheduler?.setStartupSeeking(e),diagnose:(e,t,s)=>this.diagnose(e,t,s)},h.ptsSource),this.debug=h.debug??!1,this.mode=h.mode??e,this.hasExplicitMode=void 0!==h.mode,this.lensReporter=new R((...e)=>this.log(...e)),this.cmcdAdReporter=new D(()=>this.lensReporter.handle,(...e)=>this.log(...e)),this.adBreakStatusTracker=new G({emit:(e,t)=>this.emit(e,t),effectiveFormatOf:e=>this.effectiveFormatOf(e),secondsUntilBreak:e=>this.breakScheduler?.getSecondsUntilBreak(e)??void 0,breakTransitionTimer:()=>this.breakTransitionTimer}),this.onContentSeeked=()=>{const e=this.breakScheduler?.getActiveBreak();if(!e?.controls?.snapback)return;if(this.state.snapbackSeekInFlight)return void(this.state.snapbackSeekInFlight=!1);const t="number"==typeof e.start?e.start:this.player.currentTime;Math.abs(this.player.currentTime-t)<=.5||(this.log("Snapback: seek detected during locked break, snapping back to break start"),this.state.snapbackSeekInFlight=!0,this.player.seek(t))},this.onContentWaiting=()=>{this.adPlayerController?.isAdPlaying()||this.emit("waiting",{type:"waiting",timestamp:Date.now(),source:"content"})},this.onContentPlaying=()=>{this.adPlayerController?.isAdPlaying()||(this.breakScheduler?.markPlaybackStart(),this.breakTransitionTimer?.settle("out-of-break"),!1!==this.pauseAdController?.onResume()?this.emit("playing",{type:"playing",timestamp:Date.now(),source:"content"}):this.player.pause())},this.onContentPause=()=>{this.adPlayerController?.isAdPlaying()||this.breakScheduler?.isAdStartDelayActive()||this.pauseAdController?.onPause()},this.onContentEnded=()=>{this.adPlayerController?.isAdPlaying()||this.breakScheduler?.markPlaybackEnd()},this.onContentError=e=>{this.sessionStarter?.cancelHeldImmediatePreRollOnContentError();const t=$(e,"Content playback error");this.diagnose("DA-CONTENT-PLAYBACK-ERROR",t.message,L(e)),this.breakScheduler?.setContentReloading(!0),this.contentErrorReloadGuard&&clearTimeout(this.contentErrorReloadGuard),this.contentErrorReloadGuard=setTimeout(()=>{this.contentErrorReloadGuard=null,this.breakScheduler?.setContentReloading(!1)},this.CONTENT_ERROR_RELOAD_GUARD_MS),this.emit("aderror",{type:"aderror",timestamp:Date.now(),source:"content",error:t})},this.onTimedMetadata=e=>{if(!e)return;const t=e,s=this.metadataCueTracker?.handleCue(t)??!1;this.metadataCueTracker&&this.adPlayerController?.ingestStreamClockCue(t),C(t,s,this.metadataCueTracker,this.anvatoObservedLogged,this.player.currentTime,(e,t,s)=>this.diagnose(e,t,s)),"presented"===t.phase&&v(t,this.metadataCueTracker,this.breakScheduler)},this.continueContentDuringBreak=h.continueContentDuringBreak??!1,"ssai"===this.mode)return void this.initSsai(h);if(!h.createAdAdapter)throw new Error("[OptiViewAds] createAdAdapter is required. Use the @dolby-optiview/ads-sdk package for a default HLS.js ad player, or supply your own createAdAdapter factory.");this.state.steeredSsaiOptions={maxBitrate:h.maxBitrate,autoplay:h.autoplay??!1,streamActivityMonitorId:h.gam?.streamActivityMonitorId};const T=c(h.adPreload??t),B=h.adBreakContentRecovery??s,O=u(B),M=k(h.adInsertion??r),x=o(h.chaining),V=n(h.tuneIn),K=d(h.breakWarnings),_=l(h.pdtGraceSeconds);"anvatoCue"===h.ptsSource&&(this.metadataCueTracker=new S(this.diagnose.bind(this))),this.diagnosticBuffer=new E(h.diagnostics?.bufferSize),this.breakTransitionTimer=new I(e=>{this.diagnose("DA-BREAK-TRANSITION",`Transition ${e.kind} took ${e.durationMs}ms`,{transition:e.kind,durationMs:e.durationMs,breakId:e.breakId,adPreload:T,adInsertion:M,...e.phases?{phases:e.phases}:{}})}),this.state.configSummary={mode:this.mode,adPreload:T,adBreakContentRecovery:O,adInsertion:M,chaining:{enabled:x.enabled,maxGapSeconds:x.maxGapSeconds},tuneIn:{enabled:V.enabled,minBreakDurationSeconds:V.minBreakDurationSeconds},breakWarnings:{seconds:K.seconds},ptsSource:h.ptsSource??"mediaTime",continueContentDuringBreak:this.continueContentDuringBreak,gam:h.gam?{hasAssetParameters:!1,streamActivityMonitorId:h.gam.streamActivityMonitorId}:void 0},m({adPreload:h.adPreload??t,adInsertion:h.adInsertion??r,adBreakContentRecovery:B},{preloadMode:T,insertionMode:M,contentRecovery:O},(e,t,s)=>this.diagnose(e,t,s)),this.manifestService=new g(this.debug,h.interceptManifestResponse,(e,t,s)=>this.diagnose(e,t,s),h.interceptManifestRequest),this.breakScheduler=new f(this.player,this.debug,x,void 0,V,(e,t,s)=>this.diagnose(e,t,s),K,this.metadataCueTracker,_),this.adPlayerController=new P(h.player,h.container,h.playerContainer,h.createAdAdapter,this.debug,h.gam,T,M,h.adBreakCutSafetyMarginSec??i,h.doubleBoxAudio??a,p("undefined"!=typeof navigator?navigator.userAgent:"","undefined"!=typeof navigator?navigator.maxTouchPoints??0:0),y,O),this.adPlayerController.setTransitionPhaseReporter(this.debug?e=>this.breakTransitionTimer?.phase(e):null),b(this.adPlayerController,()=>this.metadataCueTracker),this.adPlayerController.setChainResolver(x.enabled?e=>this.breakScheduler.getChainedSuccessor(e):null),this.adPlayerController.initialize();const z=(e,t)=>void 0===e||void 0===t?{}:{adIndex:e,totalAds:t};this.adPlayerController.setGamEventCallbacks({onAdFirstQuartile:(e,t,s,r)=>{this.emit("adfirstquartile",{type:"adfirstquartile",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...z(s,r)})},onAdMidpoint:(e,t,s,r)=>{this.emit("admidpoint",{type:"admidpoint",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...z(s,r)})},onAdThirdQuartile:(e,t,s,r)=>{this.emit("adthirdquartile",{type:"adthirdquartile",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...z(s,r)})}}),this.adPlayerController.setDiagnoseHandler((e,t,s)=>{this.diagnose(e,t,s)}),this.pauseAdController=w(this.adPlayerController,{debug:this.debug,diagnose:(e,t,s)=>this.diagnose(e,t,s)}),this.adPlayerController.setVolumeChangeCallback((e,t)=>{this.emit("volumechange",{type:"volumechange",timestamp:Date.now(),muted:e,volume:t})}),this.breakLifecycle=new H(this.state,{adPlayerController:this.adPlayerController,breakScheduler:this.breakScheduler,manifestService:this.manifestService,breakTransitionTimer:this.breakTransitionTimer,cmcdAdReporter:this.cmcdAdReporter,adBreakStatusTracker:this.adBreakStatusTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),effectiveFormatOf:e=>this.effectiveFormatOf(e),onBreakSettled:()=>this.sessionStarter?.applyPendingChannelSwitch()}),this.sessionStarter=new F(this.state,{player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,startLivePushback:()=>this.liveStartPushback.start(),manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,adBreakStatusTracker:this.adBreakStatusTracker,externalVendorConfigurationTracker:this.externalVendorConfigurationTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),endSessionInternal:e=>this.endSessionInternal(e),notedManifestBreakIds:e=>A(e,this.seenManifestBreakIds)});for(const[e,t]of this.contentListeners())this.player.on(e,t);this.log("OptiViewAds SDK initialized")}initSsai(e){if(!e.gam)throw new Error('[OptiViewAds] mode "ssai" requires a gam config.');if(!e.ssai?.networkCode)throw new Error('[OptiViewAds] mode "ssai" requires an ssai config (networkCode).');const t=e.ssai;this.diagnosticBuffer=new E(e.diagnostics?.bufferSize);const s=e.autoplay??!1;this.state.configSummary={mode:this.mode,adPreload:"n/a",adInsertion:"ssai",chaining:{enabled:!1,maxGapSeconds:0},tuneIn:{enabled:!1,minBreakDurationSeconds:0},gam:{networkCode:t.networkCode,hasAssetParameters:!1,streamActivityMonitorId:e.gam.streamActivityMonitorId},ssai:{maxBitrate:e.maxBitrate,autoplay:s},continueContentDuringBreak:this.continueContentDuringBreak},this.state.ssaiController=new h(this.player,{gam:e.gam,ssai:t,maxBitrate:e.maxBitrate,autoplay:s,debug:this.debug},{emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e)}),this.player.on("volumechange",()=>{this.emit("volumechange",{type:"volumechange",timestamp:Date.now(),muted:this.player.muted,volume:this.player.volume})}),this.sessionStarter=new F(this.state,{player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,startLivePushback:()=>this.liveStartPushback.start(),manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,adBreakStatusTracker:this.adBreakStatusTracker,externalVendorConfigurationTracker:this.externalVendorConfigurationTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),endSessionInternal:e=>this.endSessionInternal(e),notedManifestBreakIds:e=>A(e,this.seenManifestBreakIds)});for(const[e,t]of this.contentListeners())this.player.on(e,t);this.log("OptiViewAds SDK initialized (SSAI mode)")}contentListeners(){const e=[["seeked",this.onContentSeeked],["waiting",this.onContentWaiting],["playing",this.onContentPlaying],["pause",this.onContentPause],["ended",this.onContentEnded],["error",this.onContentError]];return this.metadataCueTracker&&e.push(["timedmetadata",this.onTimedMetadata]),e}async startSession(e){return this.sessionStarter.startSession(e)}play(){return this.adPlayerController?.isAdPlaying()?(this.log("play() suppressed — ad break is active"),Promise.resolve()):this.player.play()}pause(){this.adPlayerController?.isAdPlaying()?this.log("pause() suppressed — ad break is active"):this.player.pause()}seek(e){if(!this.state.sessionActive)return;const t=this.breakScheduler?.getActiveBreak();t?.controls?.snapback?this.log("seek() suppressed — break has snapback enabled"):(this.breakScheduler?.notifyViewerSeek(),this.player.seek(e))}get muted(){return this.adPlayerController?this.adPlayerController.muted:this.player.muted}set muted(e){this.adPlayerController?this.adPlayerController.muted=e:this.player.muted=e}get volume(){return this.adPlayerController?this.adPlayerController.volume:this.player.volume}set volume(e){this.adPlayerController?this.adPlayerController.volume=e:this.player.volume=e}skipAd(){const e=this.adBreakStatusTracker.activeBreak;if(!this.state.sessionActive||!this.adPlayerController?.isAdPlaying()||!e)return this.log("skipAd() suppressed — no active ad break"),!1;const t=e.controls?.skipOffset;if(null==t)return this.log(`skipAd() suppressed — break '${e.id}' declares no controls.skipOffset`),this.diagnose("DA-AD-SKIP-SUPPRESSED","Skip requested but break declares no skipOffset",{breakId:e.id}),!1;const s=this.adBreakStatusTracker.activeBreakElapsedSec;return s<t?(this.log(`skipAd() suppressed — skipOffset ${t}s not reached (${s}s)`),this.diagnose("DA-AD-SKIP-SUPPRESSED","Skip requested before skipOffset",{breakId:e.id,skipOffset:t,elapsedSec:s}),!1):(this.log(`skipAd() — skipping break '${e.id}' at ${s}s (skipOffset ${t}s)`),this.diagnose("DA-AD-SKIPPED","Break skipped by viewer",{breakId:e.id,skipOffset:t,elapsedSec:s}),this.cmcdAdReporter.onSkipRequested(e.id),this.adPlayerController.skipBreak(),!0)}clickAd(){const e=this.adBreakStatusTracker.activeBreak,t=this.adPlayerController?.currentAdAsset()??null;if(!(this.state.sessionActive&&this.adPlayerController?.isAdPlaying()&&e&&t))return this.log("clickAd() suppressed — no ad on screen"),null;const s=t.interaction?.clickThrough;return this.diagnose("DA-AD-CLICKED","Ad clicked",{breakId:e.id,assetId:t.id,clickThrough:s??""}),this.emit("adclick",{type:"adclick",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...s?{clickThrough:s}:{}}),s??null}endSession(){this.state.sessionActive&&this.endSessionInternal()}updateAssetParameters(e){if(!this.state.sessionActive)return void console.warn("[OptiViewAds] updateAssetParameters called but no active session.");const t="ssai"===this.mode||this.state.steeredSsaiActive;(t?this.state.ssaiController:this.adPlayerController).updateAssetParameters(e),this.log("Asset parameters updated"+(t?" (SSAI)":""))}updateAssetParameterMacros(e){if(!this.state.sessionActive)return void console.warn("[OptiViewAds] updateAssetParameterMacros called but no active session.");const t="ssai"===this.mode||this.state.steeredSsaiActive;(t?this.state.ssaiController:this.adPlayerController).updateAssetParameterMacros(e),this.log("Asset parameter macros updated"+(t?" (SSAI)":""))}getExternalVendorConfiguration(e){return _(this.state,this.externalVendorConfigurationTracker.entries,this.mode,this.adPlayerController,e)}endSessionInternal(e="end-session"){this.liveStartPushback.stop(),this.state.sessionActive=!1,this.state.sessionGeneration++,this.breakLifecycle?.reportAbandonedBreak(e),"ssai"===this.mode?this.state.ssaiController?.stop():(this.state.steeredSsaiActive&&(this.state.ssaiController?.stop(),delete this.state.ssaiController,this.state.steeredSsaiActive=!1),this.manifestService?.reset(),this.breakScheduler?.stop(),this.breakScheduler?.destroy(),this.adBreakStatusTracker.resetAdBreakStatus(),this.state.pauseAdTickInterval&&(clearInterval(this.state.pauseAdTickInterval),this.state.pauseAdTickInterval=null),this.sessionStarter?.clearHeldImmediatePreRollArm(),this.pauseAdController?.reset(),this.breakTransitionTimer?.reset(),this.adPlayerController?.stopActiveBreak(),this.adPlayerController?.releaseContentHold(),this.adPlayerController?.endGamSession()),this.state.clearSessionIdentity(),this.externalVendorConfigurationTracker.reset(),this.anvatoObservedLogged.clear(),this.seenManifestBreakIds.clear(),this.cmcdAdReporter.onSessionEnd(),this.lensReporter.endSession(),this.diagnose("DA-SESSION-ENDED","Session ended"),this.log("Session ended")}addEventListener(e,t){this.eventHandlers.has(e)||this.eventHandlers.set(e,new Set),this.eventHandlers.get(e).add(t)}removeEventListener(e,t){const s=this.eventHandlers.get(e);s&&s.delete(t)}emit(e,t){O(this.diagnosticBuffer,t),this.cmcdAdReporter.onEvent(t);const s=this.eventHandlers.get(e);if(s)for(const e of s)try{e(t)}catch(e){this.log("Event handler error:",e)}}onDiagnostic(e){this.diagnosticHandlers.add(e)}offDiagnostic(e){this.diagnosticHandlers.delete(e)}exportDiagnostics(){return K(this.state,this.diagnosticBuffer.getAll())}diagnose(e,t,s){if(this.destroyed)return;const r=M[e],i={ts:Date.now(),level:r?.level??"info",code:e,category:r?.category??"unknown",message:t,...s?{context:s}:{}};this.diagnosticBuffer.record(i);for(const e of this.diagnosticHandlers)try{e(i)}catch(e){this.log("Diagnostic handler error:",e)}this.debug&&V("[OptiViewAds]",e,t,s??"")}isAdPlaying(){return this.adPlayerController?.isAdPlaying()??!1}isPictureInPicture(){return this.adPlayerController?.isPictureInPicture()??!1}getPresentationState(){return{pictureInPicture:this.isPictureInPicture(),showing:this.adPlayerController?.isShowingAd()?"ad":"content",insertion:this.adPlayerController?.currentInsertionMode()??"overlay",windowOwner:this.adPlayerController?.pictureInPictureOwner()??null}}effectiveFormatOf(e){const t=this.adPlayerController?.declaredFormatOf(e)??B(e);return T(t,this.isPictureInPicture())}isSessionActive(){return this.state.sessionActive}getAdBreakStatus(){return this.adBreakStatusTracker.getAdBreakStatus()}destroy(){this.contentErrorReloadGuard&&(clearTimeout(this.contentErrorReloadGuard),this.contentErrorReloadGuard=null);for(const[e,t]of this.contentListeners())this.player.off(e,t);this.state.sessionActive&&this.endSessionInternal("destroy"),this.manifestService?.destroy(),this.pauseAdController?.destroy(),this.adPlayerController?.destroy(),this.state.ssaiController?.stop(),this.lensReporter.destroy(),this.eventHandlers.clear(),this.diagnosticHandlers.clear(),this.destroyed=!0,this.log("Destroyed")}log(...e){this.debug&&V("[OptiViewAds]",...e)}}
+import{DEFAULT_MODE as e,DEFAULT_AD_PRELOAD_MODE as t,DEFAULT_AD_BREAK_CONTENT_RECOVERY as s,DEFAULT_AD_INSERTION_MODE as r,DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC as i,DEFAULT_DOUBLE_BOX_AUDIO as a,resolveChaining as o,resolveTuneIn as n,resolveBreakWarnings as d,resolvePdtGraceSeconds as l}from"./types/OptiViewAdsConfig";import{SsaiController as h}from"./services/SsaiController";import{resolvePreloadMode as c}from"./services/detectPreloadMode";import{resolveContentRecovery as u}from"./services/detectContentRecovery";import{emitResolvedModeDiagnostics as m}from"./services/resolvedModeDiagnostics";import{isSingleSurfaceWebDevice as p,resolveInsertionMode as k}from"./services/detectInsertionMode";import{ManifestService as g}from"./services/ManifestService";import{BreakScheduler as y,systemClock as f}from"./services/BreakScheduler";import{MetadataCueTracker as S}from"./services/MetadataCueTracker";import{armBreakFromPresentedCue as v,diagnoseAnvatoCueObserved as C,notedManifestBreakIds as b,wireCueResume as A}from"./services/anvatoCueRuntime";import{AdPlayerController as P}from"./services/AdPlayerController";import{effectiveFormat as w}from"./services/pictureInPicture";import{ReloadGuard as B}from"./services/ReloadGuard";import{createExternalPlaybackGate as T}from"./session/createExternalPlaybackGate";import{SsbSwitchController as I}from"./session/SsbSwitch";import{createSnapbackHandler as D}from"./session/contentSnapback";import{resolveBreakFormat as R}from"./services/AdBreakSequencer";import{connectPauseAd as x}from"./services/adPlayer/connectPauseAd";import{createBreakMeasurement as E}from"./session/breakMeasurement";import{LensReporter as M}from"./services/LensReporter";import{CmcdAdReporter as O}from"./services/CmcdAdReporter";import{DiagnosticBuffer as L}from"./diagnostics/DiagnosticBuffer";import{recordEventTimeline as V}from"./diagnostics/recordEventTimeline";import{DIAGNOSTIC_CODES as H}from"./diagnostics/errorCodes";import{SDK_VERSION as G}from"./generated/version";import{playbackErrorContext as q}from"./diagnostics/playbackErrorContext";import{debugLog as F}from"./diagnostics/debugLog";import{AdBreakStatusTracker as K}from"./session/AdBreakStatusTracker";import{BreakLifecycle as $}from"./session/BreakLifecycle";import{SessionStarter as z}from"./session/SessionStarter";import{SessionState as N}from"./session/SessionState";import{LiveStartPushbackController as U}from"./services/LiveStartPushbackController";import{buildDiagnosticReport as W}from"./services/diagnosticReport";import{toPlaybackError as Q}from"./services/toPlaybackError";import{readExternalVendorConfiguration as j}from"./services/externalVendorConfigurationGetter";import{createExternalVendorConfigurationTracker as Y}from"./services/ExternalVendorConfigurationTracker";export class OptiViewAds{static get version(){return G}constructor(h){if(this.contentErrorReloadGuard=new B(e=>this.breakScheduler?.setContentReloading(e),5e3),this.eventHandlers=new Map,this.diagnosticHandlers=new Set,this.destroyed=!1,this.externalVendorConfigurationTracker=Y(e=>this.emit("externalvendorconfigurationchange",e)),this.continueContentDuringBreak=!1,this.state=new N,this.metadataCueTracker=null,this.anvatoObservedLogged=new Set,this.seenManifestBreakIds=new Set,this.player=h.player,this.liveStartPushback=new U(this.player,h.liveStartPushback,{blocked:()=>!this.state.sessionActive||this.state.channelSwitchInFlight||!!this.adPlayerController?.isAdPlaying()||!!this.state.heldImmediatePreRollId,setSeeking:e=>this.breakScheduler?.setStartupSeeking(e),diagnose:(e,t,s)=>this.diagnose(e,t,s)}),this.debug=h.debug??!1,this.mode=h.mode??e,this.hasExplicitMode=void 0!==h.mode,this.lensReporter=new M((...e)=>this.log(...e)),this.cmcdAdReporter=new O(()=>this.lensReporter.handle,(...e)=>this.log(...e)),this.externalPlayback=T(h.player,h.externalPlayback,{scheduler:()=>this.breakScheduler,diagnose:(e,t,s)=>this.diagnose(e,t,s),onAllowed:e=>this.ssbSwitch?.onAllowed(e),ssbSwitchPhase:()=>this.state.ssb?.phase??null}),this.adBreakStatusTracker=new K({externalPlaybackAllowed:()=>this.externalPlayback.managed?this.externalPlayback.isAllowedNow():void 0,deliveryMode:()=>this.state.sessionDeliveryMode??void 0,emit:(e,t)=>this.emit(e,t),effectiveFormatOf:e=>this.effectiveFormatOf(e),secondsUntilBreak:e=>this.breakScheduler?.getSecondsUntilBreak(e)??void 0,breakTransitionTimer:()=>this.breakTransitionTimer}),this.onContentSeeked=D({player:this.player,state:this.state,activeBreak:()=>this.breakScheduler?.getActiveBreak(),onViewerSeek:()=>this.sessionStarter?.discardPreparedGamSessionAfterSeek(),log:(...e)=>this.log(...e)}),this.onContentWaiting=()=>{this.adPlayerController?.isAdPlaying()||this.emit("waiting",{type:"waiting",timestamp:Date.now(),source:"content"})},this.onContentPlaying=()=>{this.adPlayerController?.isAdPlaying()||this.ssbSwitch?.isActive||(this.breakScheduler?.markPlaybackStart(),this.breakTransitionTimer?.settle("out-of-break"),!1!==this.pauseAdController?.onResume()?this.emit("playing",{type:"playing",timestamp:Date.now(),source:"content"}):this.player.pause())},this.onContentPause=()=>{this.adPlayerController?.isAdPlaying()||this.ssbSwitch?.isActive||this.breakScheduler?.isAdStartDelayActive()||this.pauseAdController?.onPause()},this.onContentEnded=()=>{this.adPlayerController?.isAdPlaying()||this.breakScheduler?.markPlaybackEnd()},this.onContentError=e=>{this.sessionStarter?.cancelHeldImmediatePreRollOnContentError();const t=Q(e,"Content playback error");this.diagnose("DA-CONTENT-PLAYBACK-ERROR",t.message,q(e)),this.contentErrorReloadGuard.arm(),this.emit("aderror",{type:"aderror",timestamp:Date.now(),source:"content",error:t})},this.onTimedMetadata=e=>{if(!e)return;const t=e,s=this.metadataCueTracker?.handleCue(t)??!1;this.metadataCueTracker&&this.adPlayerController?.ingestStreamClockCue(t),C(t,s,this.metadataCueTracker,this.anvatoObservedLogged,this.player.currentTime,(e,t,s)=>this.diagnose(e,t,s)),"presented"===t.phase&&v(t,this.metadataCueTracker,this.breakScheduler)},this.continueContentDuringBreak=h.continueContentDuringBreak??!1,"ssai"===this.mode)return void this.initSsai(h);if(!h.createAdAdapter)throw new Error("[OptiViewAds] createAdAdapter is required. Use the @dolby-optiview/ads-sdk package for a default HLS.js ad player, or supply your own createAdAdapter factory.");this.state.steeredSsaiOptions={maxBitrate:h.maxBitrate,autoplay:h.autoplay??!1,streamActivityMonitorId:h.gam?.streamActivityMonitorId};const w=c(h.adPreload??t),R=h.adBreakContentRecovery??s,V=u(R),H=k(h.adInsertion??r),G=o(h.chaining),F=n(h.tuneIn),W=d(h.breakWarnings),j=l(h.pdtGraceSeconds);"anvatoCue"===h.ptsSource&&(this.metadataCueTracker=new S(this.diagnose.bind(this))),this.diagnosticBuffer=new L(h.diagnostics?.bufferSize),({timer:this.breakTransitionTimer,recorder:this.breakChainRecorder}=E((e,t,s)=>this.diagnose(e,t,s),{adPreload:w,adInsertion:H})),this.state.configSummary={mode:this.mode,adPreload:w,adBreakContentRecovery:V,adInsertion:H,chaining:{enabled:G.enabled,maxGapSeconds:G.maxGapSeconds},tuneIn:{enabled:F.enabled,minBreakDurationSeconds:F.minBreakDurationSeconds},breakWarnings:{seconds:W.seconds},ptsSource:h.ptsSource??"mediaTime",continueContentDuringBreak:this.continueContentDuringBreak,gam:h.gam?{hasAssetParameters:!1,streamActivityMonitorId:h.gam.streamActivityMonitorId}:void 0},m({adPreload:h.adPreload??t,adInsertion:h.adInsertion??r,adBreakContentRecovery:R},{preloadMode:w,insertionMode:H,contentRecovery:V},(e,t,s)=>this.diagnose(e,t,s)),this.manifestService=new g(this.debug,h.interceptManifestResponse,(e,t,s)=>this.diagnose(e,t,s),h.interceptManifestRequest),this.breakScheduler=new y(this.player,this.debug,G,void 0,F,(e,t,s)=>this.diagnose(e,t,s),W,this.metadataCueTracker,j),this.adPlayerController=new P(h.player,h.container,h.playerContainer,h.createAdAdapter,this.debug,h.gam,w,H,h.adBreakCutSafetyMarginSec??i,h.doubleBoxAudio??a,p("undefined"!=typeof navigator?navigator.userAgent:"","undefined"!=typeof navigator?navigator.maxTouchPoints??0:0),f,V),this.adPlayerController.setTransitionPhaseReporter(this.debug?e=>this.breakTransitionTimer?.phase(e):null),A(this.adPlayerController,()=>this.metadataCueTracker),this.adPlayerController.setChainResolver(G.enabled?e=>this.breakScheduler.getChainedSuccessor(e):null),this.adPlayerController.initialize();const J=(e,t)=>void 0===e||void 0===t?{}:{adIndex:e,totalAds:t};this.adPlayerController.setGamEventCallbacks({onAdFirstQuartile:(e,t,s,r)=>{this.emit("adfirstquartile",{type:"adfirstquartile",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...J(s,r)})},onAdMidpoint:(e,t,s,r)=>{this.emit("admidpoint",{type:"admidpoint",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...J(s,r)})},onAdThirdQuartile:(e,t,s,r)=>{this.emit("adthirdquartile",{type:"adthirdquartile",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...J(s,r)})}}),this.adPlayerController.setDiagnoseHandler((e,t,s)=>{this.diagnose(e,t,s)}),this.pauseAdController=x(this.adPlayerController,{debug:this.debug,diagnose:(e,t,s)=>this.diagnose(e,t,s)}),this.adPlayerController.setVolumeChangeCallback((e,t)=>{this.emit("volumechange",{type:"volumechange",timestamp:Date.now(),muted:e,volume:t})}),this.breakLifecycle=new $(this.state,{adPlayerController:this.adPlayerController,breakScheduler:this.breakScheduler,manifestService:this.manifestService,breakTransitionTimer:this.breakTransitionTimer,breakChainRecorder:this.breakChainRecorder,cmcdAdReporter:this.cmcdAdReporter,adBreakStatusTracker:this.adBreakStatusTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),effectiveFormatOf:e=>this.effectiveFormatOf(e),onBreakSettled:()=>this.sessionStarter?.applyPendingChannelSwitch(),onBreakEnded:()=>this.externalPlayback.handleBreakEnded()});const X={player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,startLivePushback:()=>this.liveStartPushback.start(),manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,adBreakStatusTracker:this.adBreakStatusTracker,externalPlayback:this.externalPlayback,externalVendorConfigurationTracker:this.externalVendorConfigurationTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),endSessionInternal:e=>this.endSessionInternal(e),notedManifestBreakIds:e=>b(e,this.seenManifestBreakIds)};this.sessionStarter=new z(this.state,X),this.ssbSwitch=new I(this.state,this.sessionStarter,X);for(const[e,t]of this.contentListeners())this.player.on(e,t);this.log("OptiViewAds SDK initialized")}initSsai(e){if(!e.gam)throw new Error('[OptiViewAds] mode "ssai" requires a gam config.');if(!e.ssai?.networkCode)throw new Error('[OptiViewAds] mode "ssai" requires an ssai config (networkCode).');const t=e.ssai;this.diagnosticBuffer=new L(e.diagnostics?.bufferSize);const s=e.autoplay??!1;this.state.configSummary={mode:this.mode,adPreload:"n/a",adInsertion:"ssai",chaining:{enabled:!1,maxGapSeconds:0},tuneIn:{enabled:!1,minBreakDurationSeconds:0},gam:{networkCode:t.networkCode,hasAssetParameters:!1,streamActivityMonitorId:e.gam.streamActivityMonitorId},ssai:{maxBitrate:e.maxBitrate,autoplay:s},continueContentDuringBreak:this.continueContentDuringBreak},this.state.ssaiController=new h(this.player,{gam:e.gam,ssai:t,maxBitrate:e.maxBitrate,autoplay:s,debug:this.debug},{emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e)}),this.player.on("volumechange",()=>{this.emit("volumechange",{type:"volumechange",timestamp:Date.now(),muted:this.player.muted,volume:this.player.volume})}),this.sessionStarter=new z(this.state,{player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,startLivePushback:()=>this.liveStartPushback.start(),manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,externalPlayback:this.externalPlayback,adBreakStatusTracker:this.adBreakStatusTracker,externalVendorConfigurationTracker:this.externalVendorConfigurationTracker,emit:(e,t)=>this.emit(e,t),diagnose:(e,t,s)=>this.diagnose(e,t,s),log:(...e)=>this.log(...e),endSessionInternal:e=>this.endSessionInternal(e),notedManifestBreakIds:e=>b(e,this.seenManifestBreakIds)});for(const[e,t]of this.contentListeners())this.player.on(e,t);this.log("OptiViewAds SDK initialized (SSAI mode)")}contentListeners(){const e=[["seeked",this.onContentSeeked],["waiting",this.onContentWaiting],["playing",this.onContentPlaying],["pause",this.onContentPause],["ended",this.onContentEnded],["error",this.onContentError],["externalplaybackchange",this.externalPlayback.onPlayerChange]];return this.metadataCueTracker&&e.push(["timedmetadata",this.onTimedMetadata]),e}async startSession(e){return this.sessionStarter.startSession(e)}play(){return this.adPlayerController?.isAdPlaying()?(this.log("play() suppressed — ad break is active"),Promise.resolve()):this.player.play()}pause(){this.adPlayerController?.isAdPlaying()?this.log("pause() suppressed — ad break is active"):this.player.pause()}seek(e){if(!this.state.sessionActive)return;const t=this.breakScheduler?.getActiveBreak();t?.controls?.snapback?this.log("seek() suppressed — break has snapback enabled"):(this.breakScheduler?.notifyViewerSeek(),this.player.seek(e))}get muted(){return this.adPlayerController?this.adPlayerController.muted:this.player.muted}set muted(e){this.adPlayerController?this.adPlayerController.muted=e:this.player.muted=e}get volume(){return this.adPlayerController?this.adPlayerController.volume:this.player.volume}set volume(e){this.adPlayerController?this.adPlayerController.volume=e:this.player.volume=e}skipAd(){const e=this.adBreakStatusTracker.activeBreak;if(!this.state.sessionActive||!this.adPlayerController?.isAdPlaying()||!e)return this.log("skipAd() suppressed — no active ad break"),!1;const t=e.controls?.skipOffset;if(null==t)return this.log(`skipAd() suppressed — break '${e.id}' declares no controls.skipOffset`),this.diagnose("DA-AD-SKIP-SUPPRESSED","Skip requested but break declares no skipOffset",{breakId:e.id}),!1;const s=this.adBreakStatusTracker.activeBreakElapsedSec;return s<t?(this.log(`skipAd() suppressed — skipOffset ${t}s not reached (${s}s)`),this.diagnose("DA-AD-SKIP-SUPPRESSED","Skip requested before skipOffset",{breakId:e.id,skipOffset:t,elapsedSec:s}),!1):(this.log(`skipAd() — skipping break '${e.id}' at ${s}s (skipOffset ${t}s)`),this.diagnose("DA-AD-SKIPPED","Break skipped by viewer",{breakId:e.id,skipOffset:t,elapsedSec:s}),this.cmcdAdReporter.onSkipRequested(e.id),this.adPlayerController.skipBreak(),!0)}clickAd(){const e=this.adBreakStatusTracker.activeBreak,t=this.adPlayerController?.currentAdAsset()??null;if(!(this.state.sessionActive&&this.adPlayerController?.isAdPlaying()&&e&&t))return this.log("clickAd() suppressed — no ad on screen"),null;const s=t.interaction?.clickThrough;return this.diagnose("DA-AD-CLICKED","Ad clicked",{breakId:e.id,assetId:t.id,clickThrough:s??""}),this.emit("adclick",{type:"adclick",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...s?{clickThrough:s}:{}}),s??null}endSession(){this.state.sessionActive&&this.endSessionInternal()}updateAssetParameters(e){if(!this.state.sessionActive)return void console.warn("[OptiViewAds] updateAssetParameters called but no active session.");const t="ssai"===this.mode||this.state.steeredSsaiActive;(t?this.state.ssaiController:this.adPlayerController).updateAssetParameters(e),this.log("Asset parameters updated"+(t?" (SSAI)":""))}updateAssetParameterMacros(e){if(!this.state.sessionActive)return void console.warn("[OptiViewAds] updateAssetParameterMacros called but no active session.");const t="ssai"===this.mode||this.state.steeredSsaiActive;(t?this.state.ssaiController:this.adPlayerController).updateAssetParameterMacros(e),this.log("Asset parameter macros updated"+(t?" (SSAI)":""))}getExternalVendorConfiguration(e){return j(this.state,this.externalVendorConfigurationTracker.entries,this.mode,this.adPlayerController,e)}endSessionInternal(e="end-session"){this.liveStartPushback.stop(),this.externalPlayback.setManaged(!1),this.ssbSwitch?.reset(),this.state.sessionActive=!1,this.state.sessionGeneration++,this.breakLifecycle?.reportAbandonedBreak(e),"ssai"===this.mode?this.state.ssaiController?.stop():(this.state.steeredSsaiActive&&(this.state.ssaiController?.stop(),delete this.state.ssaiController,this.state.steeredSsaiActive=!1),this.manifestService?.reset(),this.breakScheduler?.stop(),this.breakScheduler?.destroy(),this.adBreakStatusTracker.resetAdBreakStatus(),this.state.pauseAdTickInterval&&(clearInterval(this.state.pauseAdTickInterval),this.state.pauseAdTickInterval=null),this.sessionStarter?.clearHeldImmediatePreRollArm(),this.pauseAdController?.reset(),this.breakChainRecorder?.flush(),this.breakTransitionTimer?.reset(),this.adPlayerController?.stopActiveBreak(),this.adPlayerController?.releaseContentHold(),this.adPlayerController?.endGamSession()),this.state.clearSessionIdentity(),this.externalVendorConfigurationTracker.reset(),this.anvatoObservedLogged.clear(),this.seenManifestBreakIds.clear(),this.cmcdAdReporter.onSessionEnd(),this.lensReporter.endSession(),this.diagnose("DA-SESSION-ENDED","Session ended"),this.log("Session ended")}addEventListener(e,t){this.eventHandlers.has(e)||this.eventHandlers.set(e,new Set),this.eventHandlers.get(e).add(t)}removeEventListener(e,t){const s=this.eventHandlers.get(e);s&&s.delete(t)}emit(e,t){V(this.diagnosticBuffer,t),this.cmcdAdReporter.onEvent(t);const s=this.eventHandlers.get(e);if(s)for(const e of s)try{e(t)}catch(e){this.log("Event handler error:",e)}}onDiagnostic(e){this.diagnosticHandlers.add(e)}offDiagnostic(e){this.diagnosticHandlers.delete(e)}exportDiagnostics(){return W(this.state,this.diagnosticBuffer.getAll())}diagnose(e,t,s){if(this.destroyed)return;const r=H[e],i={ts:Date.now(),level:r?.level??"info",code:e,category:r?.category??"unknown",message:t,...s?{context:s}:{}};this.diagnosticBuffer.record(i);for(const e of this.diagnosticHandlers)try{e(i)}catch(e){this.log("Diagnostic handler error:",e)}this.debug&&F("[OptiViewAds]",e,t,s??"")}isAdPlaying(){return this.adPlayerController?.isAdPlaying()??!1}isPictureInPicture(){return this.adPlayerController?.isPictureInPicture()??!1}getPresentationState(){return{pictureInPicture:this.isPictureInPicture(),showing:this.adPlayerController?.isShowingAd()?"ad":"content",insertion:this.adPlayerController?.currentInsertionMode()??"overlay",windowOwner:this.adPlayerController?.pictureInPictureOwner()??null}}effectiveFormatOf(e){const t=this.adPlayerController?.declaredFormatOf(e)??R(e);return w(t,this.isPictureInPicture())}isSessionActive(){return this.state.sessionActive}getAdBreakStatus(){return this.adBreakStatusTracker.getAdBreakStatus()}destroy(){this.contentErrorReloadGuard.dispose(),this.externalPlayback.dispose(),this.ssbSwitch?.dispose();for(const[e,t]of this.contentListeners())this.player.off(e,t);this.state.sessionActive&&this.endSessionInternal("destroy"),this.manifestService?.destroy(),this.pauseAdController?.destroy(),this.adPlayerController?.destroy(),this.state.ssaiController?.stop(),this.lensReporter.destroy(),this.eventHandlers.clear(),this.diagnosticHandlers.clear(),this.destroyed=!0,this.log("Destroyed")}log(...e){this.debug&&F("[OptiViewAds]",...e)}}

package/dist/OptiViewAdsExternalVendors.d.ts

@@ -3,14 +3,27 @@ import type { AssetParameterMacros } from './services/assetParameterMacros';
 import type { ExternalVendorConfiguration } from './types/ExternalVendorConfiguration';
 import type { OptiViewAdsEventHandler } from './types/Events';
 import type { DiagnosticHandler, DiagnosticReport } from './diagnostics/DiagnosticEvent';
+/** Configuration for reading manifest external-vendor parameters without a player. @category Configuration */
 export interface OptiViewAdsExternalVendorsConfig {
+    /** URL of the signed manifest to fetch. */
     manifestUrl: string;
+    /** Parameters merged beneath the entry's manifest values. */
     assetParameters?: Record<string, string>;
+    /** Named macros that are resolved when configuration is read. */
     assetParameterMacros?: AssetParameterMacros;
+    /** Optional request interceptor for manifest fetches. */
     interceptManifestRequest?: ManifestRequestInterceptor;
+    /** Optional response interceptor for manifest fetches. */
     interceptManifestResponse?: ManifestResponseInterceptor;
+    /** Enables SDK debug diagnostics. */
     debug?: boolean;
 }
+/**
+ * Reads the manifest's `external` vendor configuration entries without a player or an ad
+ * session, so the application can pass the resolved parameters to another ad provider.
+ * Call {@link start}, read entries with {@link getExternalVendorConfiguration}, and listen for
+ * `externalvendorconfigurationchange` to pick up template changes while the manifest is polled.
+ * @category SDK & Sessions */
 export declare class OptiViewAdsExternalVendors {
     private readonly manifestUrl;
     private readonly manifestService;
@@ -26,19 +39,38 @@ export declare class OptiViewAdsExternalVendors {
     private startGeneration;
     private lastValidation;
     private configSummary;
+    /**
+     * Create a reader for the manifest at `config.manifestUrl`; nothing is fetched until {@link start}.
+     * @throws Error when `manifestUrl` is blank.
+     * @category Lifecycle */
     constructor(config: OptiViewAdsExternalVendorsConfig);
+    /** Fetch the initial manifest and begin polling when configured. @category Lifecycle */
     start(): Promise<void>;
     private startInternal;
+    /** Stop polling and clear the current entries. @category Lifecycle */
     stop(): void;
+    /** Stop polling, clear entries, and release listeners. @category Lifecycle */
     destroy(): void;
+    /** Return all resolved configurations in manifest order. @category Lifecycle */
     getExternalVendorConfiguration(): ExternalVendorConfiguration[];
+    /** Return one resolved configuration using an exact provider match. @category Lifecycle */
     getExternalVendorConfiguration(provider: string): ExternalVendorConfiguration | undefined;
+    /** Replace application parameters used to resolve each configuration. @category Lifecycle */
     updateAssetParameters(parameters: Record<string, string>): void;
+    /**
+     * Merge per-name macro updates used to resolve each configuration; `null` marks a name empty
+     * (parameters that use it are omitted) and `undefined` removes it.
+     * @category Lifecycle */
     updateAssetParameterMacros(macros: AssetParameterMacroUpdates): void;
+    /** Subscribe to external-vendor configuration changes. @category Events */
     addEventListener(event: 'externalvendorconfigurationchange', handler: OptiViewAdsEventHandler<'externalvendorconfigurationchange'>): void;
+    /** Remove a configuration-change listener. @category Events */
     removeEventListener(event: 'externalvendorconfigurationchange', handler: OptiViewAdsEventHandler<'externalvendorconfigurationchange'>): void;
+    /** Subscribe to SDK diagnostics. @category Diagnostics */
     onDiagnostic(handler: DiagnosticHandler): void;
+    /** Remove a diagnostics listener. @category Diagnostics */
     offDiagnostic(handler: DiagnosticHandler): void;
+    /** Export the standalone diagnostic report. @category Diagnostics */
     exportDiagnostics(): DiagnosticReport;
     private emit;
     private diagnoseFetchFailure;

package/dist/external-playback/index.d.ts

@@ -0,0 +1,4 @@
+export { observeExternalPlayback, setExternalPlaybackAllowed } from './observeExternalPlayback';
+export type { ExternalPlaybackObserver } from './observeExternalPlayback';
+export { createReconnectHold, WEBKIT_RECONNECT_GRACE_MS, WEBKIT_RECONNECT_WINDOW_MS, } from './reconnectHold';
+export type { ReconnectHold } from './reconnectHold';

package/dist/external-playback/index.js

@@ -0,0 +1 @@
+export{observeExternalPlayback,setExternalPlaybackAllowed}from"./observeExternalPlayback";export{createReconnectHold,WEBKIT_RECONNECT_GRACE_MS,WEBKIT_RECONNECT_WINDOW_MS}from"./reconnectHold";

package/dist/external-playback/observeExternalPlayback.d.ts

@@ -0,0 +1,19 @@
+import type { ExternalPlaybackChange, ExternalPlaybackState } from '../interfaces/PlayerAdapter';
+/** Handle returned by {@link observeExternalPlayback}. */
+export interface ExternalPlaybackObserver {
+    /** Latest observed state. */
+    readonly state: ExternalPlaybackState;
+    /** Stop observing. */
+    dispose(): void;
+}
+/**
+ * Observe the element's external playback state. Prefers the Remote Playback API
+ * (`video.remote`), falling back to the WebKit AirPlay signal. Returns `null` when the element
+ * exposes neither. Only state changes are emitted. On WebKit, the wireless flag decides `active`,
+ * and a `disconnect` is held for a grace period (longer once `connecting` follows) because Safari
+ * drops and re-establishes the route by itself on a source change (`disconnect`, `connecting`,
+ * `connect`, 0.4-2.6 s), which must not read as AirPlay ending.
+ */
+export declare function observeExternalPlayback(video: HTMLVideoElement, emit: (change: ExternalPlaybackChange) => void): ExternalPlaybackObserver | null;
+/** Allow or block external playback of the element (`disableRemotePlayback`, which also gates AirPlay in Safari). */
+export declare function setExternalPlaybackAllowed(video: HTMLVideoElement, allowed: boolean): void;

package/dist/external-playback/observeExternalPlayback.js

@@ -0,0 +1 @@
+import{createReconnectHold as e}from"./reconnectHold";const n={connecting:"connecting",connect:"active",disconnect:"inactive"},t={connecting:"connecting",connected:"active",disconnected:"inactive"},c="webkitcurrentplaybacktargetiswirelesschanged";export function observeExternalPlayback(i,o){const r=i.remote,s="webkitCurrentPlaybackTargetIsWireless"in i;if(!r&&!s)return null;const a=s?"airplay":"unknown",l=()=>!0===i.webkitCurrentPlaybackTargetIsWireless;let d=s?l()?"active":r?t[r.state]:"inactive":t[r.state];const v=e=>{e!==d&&(d=e,o({state:d,target:a}))},g=e=>({get state(){return d},dispose:e});if(!s){const e=Object.keys(n).map(e=>({type:e,listener:()=>v(n[e])}));for(const{type:n,listener:t}of e)r.addEventListener(n,t);return g(()=>{for(const{type:n,listener:t}of e)r.removeEventListener(n,t)})}const f=e(()=>v("inactive")),b=()=>{f.cancel(),v("active")},u=()=>{if(f.holding&&f.sawConnecting)return f.cancel(),void v("inactive");f.holding||"inactive"===d||f.begin()},k=()=>l()?b():u();i.addEventListener(c,k);const p=[["connecting",()=>{l()||(f.holding?f.extend():v("connecting"))}],["connect",b],["disconnect",u]];if(r)for(const[e,n]of p)r.addEventListener(e,n);return g(()=>{if(f.dispose(),i.removeEventListener(c,k),r)for(const[e,n]of p)r.removeEventListener(e,n)})}export function setExternalPlaybackAllowed(e,n){e.disableRemotePlayback=!n}

package/dist/external-playback/reconnectHold.d.ts

@@ -0,0 +1,19 @@
+/** How long a drop is held before it reads as the external playback ending. */
+export declare const WEBKIT_RECONNECT_GRACE_MS = 500;
+/** How long the hold extends once the platform starts reconnecting (`connecting` after the drop). */
+export declare const WEBKIT_RECONNECT_WINDOW_MS = 5000;
+/** A drop hold: a grace period that a reconnect hint extends to a longer window. */
+export interface ReconnectHold {
+    readonly holding: boolean;
+    readonly sawConnecting: boolean;
+    /** Start the grace hold; no-op while already holding. */
+    begin(): void;
+    /** Extend to the reconnect window and remember the connecting hint; no-op when not holding. */
+    extend(): void;
+    /** Drop the hold without firing. */
+    cancel(): void;
+    /** `cancel()` for teardown. */
+    dispose(): void;
+}
+/** Create a {@link ReconnectHold} that calls `onExpire` when the hold runs out. */
+export declare function createReconnectHold(onExpire: () => void): ReconnectHold;

package/dist/external-playback/reconnectHold.js

@@ -0,0 +1 @@
+export const WEBKIT_RECONNECT_GRACE_MS=500;export const WEBKIT_RECONNECT_WINDOW_MS=5e3;export function createReconnectHold(e){let n=!1,t=!1,o=null;const c=()=>{null!==o&&clearTimeout(o),o=null},l=()=>{c(),n=!1,t=!1},r=n=>{c(),o=setTimeout(()=>{l(),e()},n)};return{get holding(){return n},get sawConnecting(){return t},begin(){n||(n=!0,t=!1,r(500))},extend(){n&&(t=!0,r(5e3))},cancel:l,dispose:l}}

package/dist/generated/diagnosticCodes.d.ts

@@ -49,6 +49,11 @@ export declare const DIAGNOSTIC_CODES: {
         readonly level: "error";
         readonly summary: "The break-manifest response failed detached-JWS signature verification (missing/malformed X-Manifest-Signature, unsupported alg, unknown kid, unknown critical param, or signature mismatch); the manifest was rejected and no breaks were scheduled. context: url, reason.";
     };
+    readonly "DA-MANIFEST-EVENT-INVALID": {
+        readonly category: "manifest";
+        readonly level: "warn";
+        readonly summary: "A channel event was ignored because its time window or configuration is invalid, or because events are unsupported for the manifest timebase. context: eventId and index when available.";
+    };
     readonly "DA-PDT-MISSING": {
         readonly category: "playback";
         readonly level: "warn";
@@ -132,12 +137,17 @@ export declare const DIAGNOSTIC_CODES: {
     readonly "DA-BREAK-TRANSITION": {
         readonly category: "break";
         readonly level: "info";
-        readonly summary: "Measured duration of a playback transition into an ad break, between two ads, between chained breaks, or back to content.";
+        readonly summary: "Measured duration of a playback transition into an ad break, between two ads, between chained breaks, or back to content. A break-to-break switch runs from the outgoing ad's end to the incoming ad's first frame and adds path (queued, late-queued or cold) and, when the incoming ad was buffered, leadMs. On web an ad-to-ad switch adds path (queued or cold) and leadMs too.";
+    };
+    readonly "DA-BREAK-CHAIN": {
+        readonly category: "chaining";
+        readonly level: "info";
+        readonly summary: "Summary of one chain of back-to-back breaks, emitted once when content plays again (or the chain is flushed): chainId, per break its id, scheduledStart, plannedDurationSec, beganAtMs, endedAtMs, playedSec, announcedDuringChain and path, per switch its gapMs and path, contentResumeMs and totalMs.";
     };
     readonly "DA-AD-SURFACE-REVEALED": {
         readonly category: "break";
         readonly level: "info";
-        readonly summary: "The ad surface became visible: how long it was held back waiting for the ad's first frame, and whether it was revealed because that frame arrived or because the wait timed out.";
+        readonly summary: "The ad surface became visible: how long it was held back waiting for the ad's first frame, and whether it was revealed because that frame arrived or because the wait timed out. On web, an ad shown before its first frame reports reason shown-before-frame with visibleGapMs, the time on screen without a picture.";
     };
     readonly "DA-BREAK-CUT-LATE": {
         readonly category: "break";
@@ -229,6 +239,11 @@ export declare const DIAGNOSTIC_CODES: {
         readonly level: "error";
         readonly summary: "The GAM/IMA session failed to initialize; GAM breaks will not serve.";
     };
+    readonly "DA-GAM-SESSION-PRELOADED": {
+        readonly category: "gam";
+        readonly level: "info";
+        readonly summary: "A GAM/IMA session was preloaded for the next event; context includes the event boundary and GAM pod identity.";
+    };
     readonly "DA-GAM-START-DEFERRED": {
         readonly category: "gam";
         readonly level: "info";
@@ -279,6 +294,31 @@ export declare const DIAGNOSTIC_CODES: {
         readonly level: "error";
         readonly summary: "The content player reported a playback error.";
     };
+    readonly "DA-EXTERNAL-PLAYBACK-CHANGED": {
+        readonly category: "playback";
+        readonly level: "info";
+        readonly summary: "The content player's external (AirPlay) playback state changed; context carries the new state and the target.";
+    };
+    readonly "DA-EXTERNAL-PLAYBACK-BLOCKED": {
+        readonly category: "playback";
+        readonly level: "warn";
+        readonly summary: "AirPlay was requested while an ad break is active or about to start; the content player stays on the device and the request is retried when the break ends.";
+    };
+    readonly "DA-SSB-SWITCH-FAILED": {
+        readonly category: "playback";
+        readonly level: "warn";
+        readonly summary: "Switching the content player to the SSB stream for AirPlay failed (context.reason: no-restore-source, load-error, load-timeout, external-not-active or receiver-paused); the SDK restores the previous content.";
+    };
+    readonly "DA-SSB-RESTORE-FAILED": {
+        readonly category: "playback";
+        readonly level: "error";
+        readonly summary: "The previous content source could not be reloaded after the SSB stream (AirPlay ended or the switch failed); the session stays in ssb delivery until the app reloads its content.";
+    };
+    readonly "DA-EXTERNAL-PLAYBACK-ALLOWED": {
+        readonly category: "playback";
+        readonly level: "info";
+        readonly summary: "An AirPlay request passed the ad-break guard; context.trigger says whether it was the request itself or the retry after a break.";
+    };
     readonly "DA-CONTENT-RESUME-STALLED": {
         readonly category: "playback";
         readonly level: "warn";
@@ -342,7 +382,7 @@ export declare const DIAGNOSTIC_CODES: {
     readonly "DA-DELIVERY-MODE-RESOLVED": {
         readonly category: "session";
         readonly level: "info";
-        readonly summary: "Delivery mode (sgai/ssai) resolved for the session at start and again on an ads-channel switch from the manifest's delivery rules (or the explicit client config), with the detected device profile.";
+        readonly summary: "Delivery mode (sgai/ssai/ssb) resolved for the session at start and again on an ads-channel switch from the manifest's delivery rules (or the explicit client config), with the detected device profile; context.source is external-playback or external-playback-ended when AirPlay switched the session to the SSB stream and back.";
     };
     readonly "DA-TARGETING-VALUE-UNKNOWN": {
         readonly category: "manifest";
@@ -417,7 +457,7 @@ export declare const DIAGNOSTIC_CODES: {
     readonly "DA-ASSET-PARAMETER-OMITTED": {
         readonly category: "break";
         readonly level: "info";
-        readonly summary: "An asset parameter value contained a customer macro that is empty (value `null`), so the parameter was not sent; for GAM `cust_params` only the `&`-separated pair containing the macro was dropped. Raised once per parameter key and macro (per dropped pair for GAM `cust_params`). context: key, macro, pair (GAM `cust_params` only), breakId, assetId.";
+        readonly summary: "An asset parameter value contained a customer macro that is empty (value `null`), so the parameter was not sent; for GAM `cust_params`, and for a static-asset value with a literal `&`, only the `&`-separated pair containing the macro was dropped. Raised once per parameter key and macro (per dropped pair when the value is split into pairs). context: key, macro, pair (split values only), breakId, assetId.";
     };
     readonly "DA-VAST-SSAI-UNSUPPORTED": {
         readonly category: "session";
@@ -517,12 +557,12 @@ export declare const DIAGNOSTIC_CODES: {
     readonly "DA-LIVE-START-PUSHBACK": {
         readonly category: "playback";
         readonly level: "info";
-        readonly summary: "Initial live playback requested a backward seek to the configured target-duration distance. Context includes enabledBy (config or ptsSource), targetDurationSec, targetDurationSource, initialOffsetSec, initialOffsetTargetDurations, requestedOffsetSec, requestedOffsetTargetDurations, targetOffsetSec, targetOffsetTargetDurations, rewindSec, rewindTargetDurations, target and windowClamped. This is a request, not proof of the landing.";
+        readonly summary: "Initial live playback requested a backward seek to the configured target-duration distance. Context includes enabledBy (always config), targetDurationSec, targetDurationSource, initialOffsetSec, initialOffsetTargetDurations, requestedOffsetSec, requestedOffsetTargetDurations, targetOffsetSec, targetOffsetTargetDurations, rewindSec, rewindTargetDurations, target and windowClamped. This is a request, not proof of the landing.";
     };
     readonly "DA-LIVE-START-PUSHBACK-SKIPPED": {
         readonly category: "playback";
         readonly level: "info";
-        readonly summary: "Initial live playback was left unchanged. The reason identifies a disabled adjustment (enabledBy says whether ptsSource or an explicit enabled decided it), an already sufficient offset, missing target duration or seekable range, invalid configuration, or no safe backward target. Available target-duration and offset measurements are included.";
+        readonly summary: "Initial live playback was left unchanged. The reason identifies a disabled adjustment (liveStartPushback.enabled is not true; enabledBy is always config), an already sufficient offset, missing target duration or seekable range, invalid configuration, or no safe backward target. Available target-duration and offset measurements are included.";
     };
     readonly "DA-LIVE-START-PUSHBACK-LANDED": {
         readonly category: "playback";