@dolby-optiview/ads-sdk-core 1.0.0-beta.1

package/dist/OptiViewAds.d.ts

@@ -0,0 +1,190 @@
+import { OptiViewAdsConfig, StartSessionConfig } from './types/OptiViewAdsConfig';
+import { AdBreakStatus, OptiViewAdsEventType, OptiViewAdsEventHandler } from './types/Events';
+import { DiagnosticHandler, DiagnosticReport } from './diagnostics/DiagnosticEvent';
+/**
+ * OptiViewAds SDK - player-agnostic ad insertion for SGAI. Constructed once per application;
+ * the customer controls monetization with startSession() / endSession().
+ *
+ * @example
+ * ```typescript
+ * import { OptiViewAds } from '@dolby-optiview/ads-sdk-core';
+ * import { HlsJsAdapter } from '@dolby-optiview/ads-sdk-adapter-hlsjs';
+ *
+ * const sdk = new OptiViewAds({
+ *   player: new HlsJsAdapter(hls, videoElement),
+ *   container: document.getElementById('container'),
+ *   createAdAdapter: (adContainer) => {
+ *     const adVideo = document.createElement('video');
+ *     adContainer.appendChild(adVideo);
+ *     const h = new Hls(); h.attachMedia(adVideo);
+ *     return new HlsJsAdapter(h, adVideo);
+ *   },
+ *   gam: {}, // presence enables GAM; the identity comes from the manifest
+ * });
+ *
+ * sdk.addEventListener('adbreakbegin', (e) => console.log('Break started', e));
+ *
+ * await sdk.startSession({
+ *   manifestUrl: 'https://manifest.example.com/v1/acme/channels/sports',
+ *   customAssetKey: 'asset-key',
+ *   assetParameters: { userId: 'abc123' },
+ * });
+ * hls.loadSource(contentUrl);
+ *
+ * sdk.updateAssetParameters({ userId: 'def456', consent: '1' });
+ * sdk.endSession();
+ * ```
+ */
+export declare class OptiViewAds {
+    /** The SDK version, readable without constructing an instance. @category Diagnostics */
+    static get version(): string;
+    private player;
+    /** 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;
+    private manifestService?;
+    private breakScheduler?;
+    private adPlayerController?;
+    private pauseAdController?;
+    private mode;
+    private readonly hasExplicitMode;
+    private eventHandlers;
+    private diagnosticHandlers;
+    private destroyed;
+    private diagnosticBuffer;
+    /** Whether eligible replacement breaks may keep content playing. */
+    private continueContentDuringBreak;
+    private readonly lensReporter;
+    private readonly cmcdAdReporter;
+    private debug;
+    private readonly state;
+    private breakLifecycle?;
+    private sessionStarter;
+    private readonly adBreakStatusTracker;
+    private breakTransitionTimer?;
+    private readonly onContentSeeked;
+    private readonly onContentWaiting;
+    private readonly onContentPlaying;
+    private readonly onContentPause;
+    private readonly onContentEnded;
+    private readonly onContentError;
+    private metadataCueTracker;
+    /** Dedup keys of cues already surfaced as DA-ANVATO-CUE-OBSERVED; a re-fired ID3 frame must not spam diagnostics. */
+    private anvatoObservedLogged;
+    /** Break ids already reported as newly seen on DA-MANIFEST-POLLED (see notedManifestBreakIds). */
+    private seenManifestBreakIds;
+    private readonly onTimedMetadata;
+    constructor(config: OptiViewAdsConfig);
+    /** SSAI-mode construction: no manifest service, break scheduler, or ad-player overlay. */
+    private initSsai;
+    /** Content player events both modes subscribe to; unsubscribed again in destroy(). */
+    private contentListeners;
+    /**
+     * Start monetization for a piece of content: begins manifest polling and (if configured)
+     * GAM session initialization. Ends any previously active session first.
+     * @category Lifecycle */
+    startSession(config: StartSessionConfig): Promise<void>;
+    /** Resume content playback. No-op during a content-locking ad break. @category Playback & UI */
+    play(): Promise<void>;
+    /** Pause content playback. No-op during a content-locking ad break. @category Playback & UI */
+    pause(): void;
+    /** Seek the content stream (seconds). Blocked during breaks with controls.snapback; no-op without a session. @category Playback & UI */
+    seek(time: number): void;
+    /**
+     * Unified mute state: targets whichever player is audible — the ad player during a break,
+     * the content player otherwise — and bridges into IMA for a CSAI ad (IMA manages its own audio path).
+     *
+     * @example
+     * muteButton.onclick = () => { sdk.muted = !sdk.muted; };
+     * sdk.addEventListener('volumechange', (e) => {
+     *   muteButton.textContent = e.muted ? 'Unmute' : 'Mute';
+     * });
+     * @category Playback & UI */
+    get muted(): boolean;
+    set muted(value: boolean);
+    /** Unified volume (0-1). See {@link muted} for which player is the effective target. @category Playback & UI */
+    get volume(): number;
+    set volume(value: number);
+    /**
+     * Skip the running ad break when the manifest's `controls.skipOffset` allows it. Returns
+     * `true` when applied (balanced `adend` + `adbreakend`), `false` when suppressed (no active
+     * break, no skip control, or before the offset). Suppression is diagnosed as
+     * `DA-AD-SKIP-SUPPRESSED`. Use {@link getAdBreakStatus} for a "Skip in Ns" affordance.
+     * @category Playback & UI */
+    skipAd(): boolean;
+    /**
+     * Report a click on the current ad and emit `adclick` with its `interaction.clickThrough`.
+     * Returns the destination URL, or `null` when no ad or click-through URL is available.
+     * The SDK does not open the URL; your application controls navigation.
+     * @category Playback & UI */
+    clickAd(): string | null;
+    /** Stop monetization: stops manifest polling, break scheduling, and resets the GAM session. @category Lifecycle */
+    endSession(): void;
+    /**
+     * Replace the live-update layer of the asset parameters for future breaks. Highest of the
+     * three layers, per key; it **replaces** the previous update (IMA `replaceAdTagParameters()`
+     * semantics). Consumed by GAM pods (IMA `adTagParameters`) and by VAST assets (appended to
+     * the tag URL). No-op with a warning without an active session.
+     * @category Lifecycle */
+    updateAssetParameters(params: Record<string, string>): void;
+    private endSessionInternal;
+    /**
+     * Subscribe to an SDK event.
+     * @category Events */
+    addEventListener<T extends OptiViewAdsEventType>(event: T, handler: OptiViewAdsEventHandler<T>): void;
+    /**
+     * Unsubscribe from an SDK event. Pass the same handler reference that was
+     * given to {@link addEventListener}; unknown handlers are ignored.
+     * @category Events */
+    removeEventListener<T extends OptiViewAdsEventType>(event: T, handler: OptiViewAdsEventHandler<T>): void;
+    private emit;
+    /** Redacted timeline entry for `exportDiagnostics()`: only stable identifiers (type, source, break/asset ids). */
+    private recordEventTimeline;
+    /** Subscribe to the structured diagnostic stream (stable `code`, `category`, `level`, JSON `context`). @category Diagnostics */
+    onDiagnostic(handler: DiagnosticHandler): void;
+    /** Unsubscribe from the structured diagnostic stream. @category Diagnostics */
+    offDiagnostic(handler: DiagnosticHandler): void;
+    /** Self-contained, redacted diagnostic report (no secrets or ad-tag-parameter values). @category Diagnostics */
+    exportDiagnostics(): DiagnosticReport;
+    /** Only Anvato break cues carry a schedulable instant; SSAI ID3, EXT-X-DATERANGE and emsg pass through untouched. */
+    private armBreakFromPresentedCue;
+    /**
+     * Break ids not seen in a manifest before this session. A break that leaves and returns is
+     * NOT re-reported: the metric is when the backend first signalled it.
+     */
+    private notedManifestBreakIds;
+    /** Only `type=cue` frames are surfaced; captions/beacons arrive once per segment and would flood the buffer. */
+    private diagnoseAnvatoCueObserved;
+    /** Push to the ring buffer, notify subscribers, mirror to the console in debug. Category/level come from the code catalog. */
+    private diagnose;
+    /** Whether an ad is currently playing. @category Playback & UI */
+    isAdPlaying(): boolean;
+    /** Whether the content player is in picture-in-picture. The browser reports this directly; nothing to wire up. @category Playback & UI */
+    isPictureInPicture(): boolean;
+    /** Current picture-in-picture status, visible media, window owner, and insertion mode.
+     * Use this snapshot to keep your player UI aligned with the SDK.
+     * @category Playback & UI */
+    getPresentationState(): {
+        pictureInPicture: boolean;
+        showing: 'ad' | 'content';
+        /** which element owns the PiP window — null when there is none (web only) */
+        windowOwner: 'content' | 'ad' | null;
+        /** `overlay` (own element) or `shared-element` (through the content element); content behaviour and `windowOwner` differ between them. */
+        insertion: 'overlay' | 'shared-element';
+    };
+    /**
+     * The format `breakInfo` will ACTUALLY play as. In PiP the browser renders only the PiP'd
+     * video, so multi-surface formats play as `single`; the declared one is kept in `DA-PIP-FORMAT-OVERRIDE`.
+     */
+    private effectiveFormatOf;
+    /** Whether a session is currently active. @category Lifecycle */
+    isSessionActive(): boolean;
+    /** Current playback-gated ad break status; for polling when an `adbreakstatus` event was missed. @category Playback & UI */
+    getAdBreakStatus(): AdBreakStatus;
+    /** Clean up all resources. Call when the SDK is no longer needed. @category Lifecycle */
+    destroy(): void;
+    /** Descriptive Error from an adapter media error, surfacing the underlying code/message. */
+    private toPlaybackError;
+    private log;
+}

package/dist/OptiViewAds.js

@@ -0,0 +1 @@
+import{DEFAULT_MODE as e,DEFAULT_AD_PRELOAD_MODE as t,DEFAULT_AD_INSERTION_MODE as s,DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC as r,DEFAULT_DOUBLE_BOX_AUDIO as i,resolveChaining as a,resolveTuneIn as n,resolveBreakWarnings as o,resolvePdtGraceSeconds as d}from"./types/OptiViewAdsConfig";import{SsaiController as l}from"./services/SsaiController";import{resolvePreloadMode as h}from"./services/detectPreloadMode";import{isSingleSurfaceWebDevice as c,resolveInsertionMode as u}from"./services/detectInsertionMode";import{ManifestService as m}from"./services/ManifestService";import{BreakScheduler as p}from"./services/BreakScheduler";import{MetadataCueTracker as g,isAnvatoCue as k,parseAnvatoPayload as f}from"./services/MetadataCueTracker";import{AdPlayerController as y}from"./services/AdPlayerController";import{effectiveFormat as S}from"./services/pictureInPicture";import{resolveBreakFormat as A}from"./services/AdBreakSequencer";import{connectPauseAd as v}from"./services/adPlayer/connectPauseAd";import{BreakTransitionTimer as b}from"./services/BreakTransitionTimer";import{LensReporter as C}from"./services/LensReporter";import{CmcdAdReporter as P}from"./services/CmcdAdReporter";import{DiagnosticBuffer as T}from"./diagnostics/DiagnosticBuffer";import{DIAGNOSTIC_CODES as B}from"./diagnostics/errorCodes";import{SDK_VERSION as w}from"./generated/version";import{playbackErrorContext as D}from"./diagnostics/playbackErrorContext";import{debugLog as E}from"./diagnostics/debugLog";import{AdBreakStatusTracker as I}from"./session/AdBreakStatusTracker";import{BreakLifecycle as O}from"./session/BreakLifecycle";import{SessionStarter as R}from"./session/SessionStarter";import{SessionState as M}from"./session/SessionState";export class OptiViewAds{static get version(){return w}constructor(l){if(this.contentErrorReloadGuard=null,this.CONTENT_ERROR_RELOAD_GUARD_MS=5e3,this.eventHandlers=new Map,this.diagnosticHandlers=new Set,this.destroyed=!1,this.continueContentDuringBreak=!1,this.state=new M,this.metadataCueTracker=null,this.anvatoObservedLogged=new Set,this.seenManifestBreakIds=new Set,this.player=l.player,this.debug=l.debug??!1,this.mode=l.mode??e,this.hasExplicitMode=void 0!==l.mode,this.lensReporter=new C((...e)=>this.log(...e)),this.cmcdAdReporter=new P(()=>this.lensReporter.handle,(...e)=>this.log(...e)),this.adBreakStatusTracker=new I({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=>{const t=this.toPlaybackError(e,"Content playback error");this.diagnose("DA-CONTENT-PLAYBACK-ERROR",t.message,D(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.diagnoseAnvatoCueObserved(t,s),"presented"===t.phase&&this.armBreakFromPresentedCue(t)},this.continueContentDuringBreak=l.continueContentDuringBreak??!1,"ssai"===this.mode)return void this.initSsai(l);if(!l.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:l.maxBitrate,autoplay:l.autoplay??!1,streamActivityMonitorId:l.gam?.streamActivityMonitorId};const k=h(l.adPreload??t),f=u(l.adInsertion??s),S=a(l.chaining),A=n(l.tuneIn),B=o(l.breakWarnings),w=d(l.pdtGraceSeconds);"anvatoCue"===l.ptsSource&&(this.metadataCueTracker=new g),this.diagnosticBuffer=new T(l.diagnostics?.bufferSize),this.breakTransitionTimer=new b(e=>{this.diagnose("DA-BREAK-TRANSITION",`Transition ${e.kind} took ${e.durationMs}ms`,{transition:e.kind,durationMs:e.durationMs,breakId:e.breakId,adPreload:k,adInsertion:f,...e.phases?{phases:e.phases}:{}})}),this.state.configSummary={mode:this.mode,adPreload:k,adInsertion:f,chaining:{enabled:S.enabled,maxGapSeconds:S.maxGapSeconds},tuneIn:{enabled:A.enabled,minBreakDurationSeconds:A.minBreakDurationSeconds},breakWarnings:{seconds:B.seconds},ptsSource:l.ptsSource??"mediaTime",continueContentDuringBreak:this.continueContentDuringBreak,gam:l.gam?{hasAssetParameters:!1,streamActivityMonitorId:l.gam.streamActivityMonitorId}:void 0};const E=l.adPreload??t;this.diagnose("DA-PRELOAD-MODE-RESOLVED",`Ad preload mode: ${k}`+(E!==k?` (configured "${E}")`:""),{configured:E,resolved:k}),"shared-element"===l.adInsertion&&"overlay"===f&&this.diagnose("DA-SHARED-ELEMENT-UNSUPPORTED",'adInsertion "shared-element" is unsupported on this platform (non-iPhone/iPod); fell back to "overlay".',{configured:"shared-element",resolved:f}),this.manifestService=new m(this.debug,l.interceptManifestResponse,(e,t,s)=>this.diagnose(e,t,s),l.interceptManifestRequest),this.breakScheduler=new p(this.player,this.debug,S,void 0,A,(e,t,s)=>this.diagnose(e,t,s),B,this.metadataCueTracker,w),this.adPlayerController=new y(l.player,l.container,l.playerContainer,l.createAdAdapter,this.debug,l.gam,k,f,l.adBreakCutSafetyMarginSec??r,l.doubleBoxAudio??i,c("undefined"!=typeof navigator?navigator.userAgent:"","undefined"!=typeof navigator?navigator.maxTouchPoints??0:0)),this.adPlayerController.setTransitionPhaseReporter(this.debug?e=>this.breakTransitionTimer?.phase(e):null),this.adPlayerController.setChainResolver(S.enabled?e=>this.breakScheduler.getChainedSuccessor(e):null),this.adPlayerController.initialize();const L=(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,...L(s,r)})},onAdMidpoint:(e,t,s,r)=>{this.emit("admidpoint",{type:"admidpoint",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...L(s,r)})},onAdThirdQuartile:(e,t,s,r)=>{this.emit("adthirdquartile",{type:"adthirdquartile",timestamp:Date.now(),break:e,format:this.effectiveFormatOf(e),asset:t,...L(s,r)})}}),this.adPlayerController.setDiagnoseHandler((e,t,s)=>{this.diagnose(e,t,s)}),this.pauseAdController=v(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 O(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 R(this.state,{player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,adBreakStatusTracker:this.adBreakStatusTracker,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=>this.notedManifestBreakIds(e)});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 T(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 l(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 R(this.state,{player:this.player,debug:this.debug,mode:this.mode,hasExplicitMode:this.hasExplicitMode,continueContentDuringBreak:this.continueContentDuringBreak,manifestService:this.manifestService,breakScheduler:this.breakScheduler,adPlayerController:this.adPlayerController,pauseAdController:this.pauseAdController,breakLifecycle:this.breakLifecycle,cmcdAdReporter:this.cmcdAdReporter,lensReporter:this.lensReporter,adBreakStatusTracker:this.adBreakStatusTracker,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=>this.notedManifestBreakIds(e)});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){if("ssai"===this.mode||this.state.steeredSsaiActive)return this.state.ssaiController.updateAssetParameters(e),void this.log("Asset parameters updated (SSAI)");this.adPlayerController.updateAssetParameters(e),this.log("Asset parameters updated")}else console.warn("[OptiViewAds] updateAssetParameters called but no active session.")}endSessionInternal(e="end-session"){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.pauseAdController?.reset(),this.breakTransitionTimer?.reset(),this.adPlayerController?.stopActiveBreak(),this.adPlayerController?.releaseContentHold(),this.adPlayerController?.endGamSession()),this.state.clearSessionIdentity(),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){this.recordEventTimeline(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)}}recordEventTimeline(e){const t={eventType:e.type},s=e;s.source&&(t.source=s.source),s.break?.id&&(t.breakId=s.break.id),s.asset?.id&&(t.assetId=s.asset.id),this.diagnosticBuffer.record({ts:e.timestamp,level:"aderror"===e.type?"error":"info",code:"DA-EVENT",category:"event",message:`SDK event: ${e.type}`,context:t})}onDiagnostic(e){this.diagnosticHandlers.add(e)}offDiagnostic(e){this.diagnosticHandlers.delete(e)}exportDiagnostics(){const e={...this.state.configSummary,...this.state.manifestOrigin?{manifestOrigin:this.state.manifestOrigin}:{},...this.state.configSummary.ssai&&this.state.stitcherOrigin?{ssai:{...this.state.configSummary.ssai,stitcherOrigin:this.state.stitcherOrigin}}:{}};return{sdkVersion:w,generatedAt:Date.now(),userAgent:"undefined"!=typeof navigator?navigator.userAgent:null,config:e,diagnostics:this.diagnosticBuffer.getAll()}}armBreakFromPresentedCue(e){if(!this.metadataCueTracker||!this.breakScheduler||!k(e))return;const t=f(e.messageData??"");if("cue"!==t.type)return;const s=Number(t.pts);Number.isFinite(s)&&this.breakScheduler.notifyCuePresented(s)}notedManifestBreakIds(e){const t=[];for(const s of e.breaks)this.seenManifestBreakIds.has(s.id)||(this.seenManifestBreakIds.add(s.id),t.push(s.id));return t}diagnoseAnvatoCueObserved(e,t){if(!this.metadataCueTracker||!k(e))return;const s=e.messageData??"",r=f(s);if("cue"!==r.type)return;const i=`${e.startTime}|${s}`;if(this.anvatoObservedLogged.has(i))return;this.anvatoObservedLogged.add(i);const a=Number(r.pts);this.diagnose("DA-ANVATO-CUE-OBSERVED",`Anvato cue observed: pts=${r.pts} at media time ${e.startTime}s`,{pts:Number.isFinite(a)?a:r.pts,mediaTime:e.startTime,playheadSec:this.player.currentTime,recorded:t,payload:s.slice(0,300)})}diagnose(e,t,s){if(this.destroyed)return;const r=B[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&&E("[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)??A(e);return S(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")}toPlaybackError(e,t){const s=e;if(s&&("number"==typeof s.code||s.message)){const e="number"==typeof s.code?` (code ${s.code})`:"",r=s.message?`: ${s.message}`:"";return new Error(`${t}${e}${r}`)}return new Error(t)}log(...e){this.debug&&E("[OptiViewAds]",...e)}}

package/dist/config/keys.d.ts

@@ -0,0 +1,23 @@
+import { ManifestSignatureKey } from '../services/manifestSignature';
+/**
+ * The embedded trusted Break Manifest signing keys (raw Ed25519 public keys,
+ * base64url). Baked into the SDK at build time — never fetched at runtime.
+ * Multiple keys are listed so the backend can rotate: a new key is shipped
+ * here first, the backend switches `kid`, then the old entry is removed.
+ */
+export declare const PRODUCTION_MANIFEST_KEYS: ReadonlyArray<{
+    kid: string;
+    publicKey: string;
+}>;
+export declare function decodeManifestKey(entry: {
+    kid: string;
+    publicKey: string;
+}): ManifestSignatureKey;
+/**
+ * The trust list every published Web SDK artifact embeds — release, beta,
+ * feature, or custom builds all use exactly these three backend keys. No
+ * branch, version, environment, or CI selection changes it, and there is no
+ * runtime option to add keys. The repo-public test key (`conformance/keys/`)
+ * lives only in test-only code under `__tests__` and private test apps.
+ */
+export declare function embeddedManifestKeys(): ManifestSignatureKey[];

package/dist/config/keys.js

@@ -0,0 +1 @@
+export const PRODUCTION_MANIFEST_KEYS=[{kid:"ads-prod-2026-08",publicKey:"h6jbWWoz1G1_Osj1wkDJT_I8ZNtLhix1YuMoBP8coNs"},{kid:"ads-staging-2026-08",publicKey:"wVszV8cvem7uhwSh06DjzXRN_4p3JBbEhPHlhrkvuNA"},{kid:"ads-dev-2026-08",publicKey:"bsz__yOAX__YQ_USwfADt8_KoDkc6fxriRVdFHxkmdo"}];export function decodeManifestKey(e){const t=e.publicKey.replace(/-/g,"+").replace(/_/g,"/"),d=atob(t),i=new Uint8Array(d.length);for(let e=0;e<d.length;e++)i[e]=d.charCodeAt(e);return{kid:e.kid,publicKey:i}}export function embeddedManifestKeys(){return PRODUCTION_MANIFEST_KEYS.map(decodeManifestKey)}

package/dist/diagnostics/DiagnosticBuffer.d.ts

@@ -0,0 +1,33 @@
+import { DiagnosticEvent } from './DiagnosticEvent';
+/**
+ * Default number of records retained in the diagnostic ring buffer.
+ */
+export declare const DEFAULT_DIAGNOSTIC_BUFFER_SIZE = 200;
+/**
+ * A bounded, in-memory ring buffer of {@link DiagnosticEvent}s.
+ *
+ * Retains the most recent `size` records (diagnostics + SDK-event timeline) so
+ * `OptiViewAds.exportDiagnostics()` can produce a self-contained report without
+ * unbounded memory growth on long-running live sessions.
+ */
+export declare class DiagnosticBuffer {
+    private readonly size;
+    private events;
+    constructor(size?: number);
+    /**
+     * Append a record, evicting the oldest when the buffer is full.
+     */
+    record(event: DiagnosticEvent): void;
+    /**
+     * Return a shallow copy of the retained records, oldest first.
+     */
+    getAll(): DiagnosticEvent[];
+    /**
+     * Drop all retained records.
+     */
+    clear(): void;
+    /**
+     * Configured capacity of the buffer.
+     */
+    get capacity(): number;
+}

package/dist/diagnostics/DiagnosticBuffer.js

@@ -0,0 +1 @@
+export const DEFAULT_DIAGNOSTIC_BUFFER_SIZE=200;export class DiagnosticBuffer{constructor(t=200){this.events=[],this.size=t>0?Math.floor(t):200}record(t){this.events.push(t),this.events.length>this.size&&this.events.splice(0,this.events.length-this.size)}getAll(){return[...this.events]}clear(){this.events=[]}get capacity(){return this.size}}

package/dist/diagnostics/DiagnosticEvent.d.ts

@@ -0,0 +1,71 @@
+import type { PtsSource } from '../types/OptiViewAdsConfig';
+import { DiagnosticCategory, DiagnosticLevel } from './errorCodes';
+/** Machine-readable diagnostic record (stable `code`, `category`, JSON-serialisable `context`) behind `onDiagnostic()` and `exportDiagnostics()`. @category Diagnostics */
+export interface DiagnosticEvent {
+    /** Unix epoch milliseconds when the record was created. */
+    ts: number;
+    /** Severity of the record. */
+    level: DiagnosticLevel;
+    /** Stable, machine-readable code (e.g. `DA-MANIFEST-FETCH-FAILED`). */
+    code: string;
+    /** Functional area the record relates to. */
+    category: DiagnosticCategory;
+    /** Human-readable message. */
+    message: string;
+    /** Optional JSON-serialisable structured context. Never contains secrets. */
+    context?: Record<string, unknown>;
+}
+/** Handler for the structured diagnostic stream. @category Diagnostics */
+export type DiagnosticHandler = (event: DiagnosticEvent) => void;
+/** Redacted SDK configuration for a diagnostic report; secrets and PII (e.g. ad tag parameter VALUES) are stripped. @category Diagnostics */
+export interface ConfigSummary {
+    /** Ad insertion architecture in effect (`sgai` or `ssai`). */
+    mode: string;
+    /** Origin only (scheme + host [+ port]); path/query may carry channel identity or a signed token. Absent before startSession() and in SSAI. */
+    manifestOrigin?: string;
+    adPreload: string;
+    adInsertion: string;
+    chaining: {
+        enabled: boolean;
+        maxGapSeconds: number;
+    };
+    tuneIn: {
+        enabled: boolean;
+        minBreakDurationSeconds: number;
+    };
+    /** Proactive pre-break warning configuration, if supplied. */
+    breakWarnings?: {
+        seconds: number[];
+    };
+    /** How PTS-timebase break starts are resolved (`mediaTime` or `anvatoCue`). */
+    ptsSource?: PtsSource;
+    /** Whether eligible replacement breaks may keep content playing. */
+    continueContentDuringBreak?: boolean;
+    gam?: {
+        /** CONFIGURED network code, `ssai` only; in `sgai` the identity is manifest-authored (`DA-GAM-CONFIG-RESOLVED`). */
+        networkCode?: string;
+        /** Whether any asset parameters were supplied for this session; values are omitted, only presence is reported. */
+        hasAssetParameters: boolean;
+        streamActivityMonitorId?: string | undefined;
+    } | undefined;
+    /** SSAI stitcher summary — present only in `ssai` mode. */
+    ssai?: {
+        /** Origin of the stitcher master URL — same redaction as manifestOrigin. */
+        stitcherOrigin?: string;
+        maxBitrate?: number | undefined;
+        autoplay: boolean;
+    } | undefined;
+}
+/** Self-contained, redacted report for a support engineer or the troubleshooting agent. @category Diagnostics */
+export interface DiagnosticReport {
+    /** SDK version that produced the report. */
+    sdkVersion: string;
+    /** Unix epoch milliseconds when the report was generated. */
+    generatedAt: number;
+    /** Browser/runtime user agent, or null when unavailable. */
+    userAgent: string | null;
+    /** Redacted configuration summary. */
+    config: ConfigSummary;
+    /** Recent diagnostics and SDK-event timeline, oldest first. */
+    diagnostics: DiagnosticEvent[];
+}

package/dist/diagnostics/DiagnosticEvent.js

@@ -0,0 +1 @@
+export{};

package/dist/diagnostics/debugLog.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Internal sink for core's debug-gated `log()` helpers.
+ *
+ * Call sites keep their own debug gating. This single console sink is
+ * deliberately not exported from any package entry point, so it adds no
+ * public API surface.
+ */
+export declare function debugLog(scope: string, ...args: unknown[]): void;

package/dist/diagnostics/debugLog.js

@@ -0,0 +1 @@
+export function debugLog(o,...e){console.log(o,...e)}

package/dist/diagnostics/errorCodes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Stable diagnostic taxonomy for the OptiViewAds SDK.
+ *
+ * Each code is a stable, machine-readable identifier that maps a runtime
+ * condition to a category and severity. Codes are consumed by:
+ * - the structured diagnostic stream (`OptiViewAds.onDiagnostic`),
+ * - `OptiViewAds.exportDiagnostics()` reports,
+ * - the `@dolby-optiview/ads-sdk-mcp` troubleshooting tools and their knowledge base.
+ *
+ * Codes are part of the public contract: do not rename or repurpose an existing
+ * code. Add new codes instead. The catalog itself ({@link DIAGNOSTIC_CODES}) is
+ * GENERATED from the language-neutral source of truth at
+ * `taxonomy/diagnostic-codes.json` (shared with the Kotlin/Swift cores); the
+ * human-readable docs in `packages/sdk/ai/reference/error-codes.md` derive from it.
+ * Edit the JSON source and run `npm run gen:taxonomy`, not this file.
+ */
+import { DIAGNOSTIC_CODES } from '../generated/diagnosticCodes';
+export { DIAGNOSTIC_CODES };
+/**
+ * Functional area a diagnostic relates to.
+ * @category Diagnostics */
+export type DiagnosticCategory = 'manifest' | 'session' | 'break' | 'preload' | 'gam' | 'playback' | 'chaining' | 'event' | 'lifecycle';
+/**
+ * Severity of a diagnostic record.
+ * @category Diagnostics */
+export type DiagnosticLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Static metadata describing a diagnostic code.
+ * @category Diagnostics */
+export interface DiagnosticCodeInfo {
+    /** Functional area. */
+    category: DiagnosticCategory;
+    /** Default severity for this code. */
+    level: DiagnosticLevel;
+    /** One-line human summary of what the code means. */
+    summary: string;
+}
+/**
+ * Union of all known, statically-typed diagnostic codes.
+ * @category Diagnostics */
+export type KnownDiagnosticCode = keyof typeof DIAGNOSTIC_CODES;
+/**
+ * Look up the metadata for a known diagnostic code.
+ */
+export declare function getDiagnosticCodeInfo(code: KnownDiagnosticCode): DiagnosticCodeInfo;

package/dist/diagnostics/errorCodes.js

@@ -0,0 +1 @@
+import{DIAGNOSTIC_CODES as o}from"../generated/diagnosticCodes";export{o as DIAGNOSTIC_CODES};export function getDiagnosticCodeInfo(e){return o[e]}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,6 @@
+export type { DiagnosticEvent, DiagnosticHandler, DiagnosticReport, ConfigSummary, } from './DiagnosticEvent';
+export type { DiagnosticCategory, DiagnosticLevel, DiagnosticCodeInfo, KnownDiagnosticCode, } from './errorCodes';
+export { DIAGNOSTIC_CODES, getDiagnosticCodeInfo } from './errorCodes';
+export { DiagnosticBuffer, DEFAULT_DIAGNOSTIC_BUFFER_SIZE } from './DiagnosticBuffer';
+export { SDK_VERSION } from '../generated/version';
+export { playbackErrorContext } from './playbackErrorContext';

package/dist/diagnostics/index.js

@@ -0,0 +1 @@
+export{DIAGNOSTIC_CODES,getDiagnosticCodeInfo}from"./errorCodes";export{DiagnosticBuffer,DEFAULT_DIAGNOSTIC_BUFFER_SIZE}from"./DiagnosticBuffer";export{SDK_VERSION}from"../generated/version";export{playbackErrorContext}from"./playbackErrorContext";

package/dist/diagnostics/playbackErrorContext.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structured detail for `DA-CONTENT-PLAYBACK-ERROR` / ad playback errors.
+ *
+ * The diagnostic used to carry the error's message and nothing else, and on every platform
+ * that message is the CATEGORY, not the cause: a media3 `PlaybackException` stringifies to
+ * "Source error", a `MediaError` to a terse browser string. Whoever is reading a failed run
+ * needs the next layer down — the HTTP status, the host that refused, the decoder that gave
+ * up — and it is one dereference away at the point the diagnostic is raised.
+ *
+ * That gap cost a real investigation: an intermittent BrowserStack failure produced
+ * `ERROR DA-CONTENT-PLAYBACK-ERROR` with no reason attached, while a neighbouring diagnostic
+ * (which happened to format its own message) named the unreachable host and port outright.
+ *
+ * Deliberately structural, not player-specific: the core drives a `PlayerAdapter` and must
+ * not depend on any one player's types. Everything here comes from the shape an error
+ * already has — a code, a name, a cause chain.
+ */
+/**
+ * Flattens a playback error into diagnostic context. Never throws and never returns
+ * undefined keys — a diagnostic raised on an error path must not fail on the error.
+ */
+export declare function playbackErrorContext(mediaError: unknown): Record<string, unknown>;

package/dist/diagnostics/playbackErrorContext.js

@@ -0,0 +1 @@
+const e={1:"MEDIA_ERR_ABORTED",2:"MEDIA_ERR_NETWORK",3:"MEDIA_ERR_DECODE",4:"MEDIA_ERR_SRC_NOT_SUPPORTED"},t=new Set(["server","via","x-served-by","x-cache","x-cache-hits","x-cache-status","x-proxy","cf-ray","cf-cache-status","x-amz-cf-pop","x-amz-request-id","x-fastly-request-id","x-akamai-request-id","x-envoy-upstream-service-time","x-geo-country","x-country-code","cf-ipcountry","x-error","x-error-message","x-ratelimit-remaining","retry-after","www-authenticate","content-type","age","x-request-id","x-trace-id","location"]);function r(e){const r={},o=e.response??{},s=e.url??e.uri??o.url;"string"==typeof s&&s&&(r.url=s);const n=e.networkDetails??o.networkDetails??{},a=e.responseURL??o.responseURL??n.responseURL??e.finalUrl;"string"==typeof a&&a&&a!==r.url&&(r.finalUrl=a);const c=o.code??o.status??e.status??e.httpStatus;"number"==typeof c&&(r.httpStatus=c);const i=o.headers??e.headers??e.responseHeaders,u={};if(i&&"object"==typeof i)for(const[e,r]of Object.entries(i))!t.has(e.toLowerCase())||"string"!=typeof r&&"number"!=typeof r||(u[e.toLowerCase()]=String(r));const p=Object.entries(u).map(([e,t])=>`${e}=${t}`);return p.length&&(r.responseHeaders=p.join("; ").slice(0,400)),r}export function playbackErrorContext(t){const o={};if(null==t)return o;const s=t;"number"==typeof s.code?(o.errorCode=s.code,e[s.code]&&(o.errorName=e[s.code])):"string"==typeof s.code&&s.code&&(o.errorCode=s.code),"string"==typeof s.name&&s.name&&"Error"!==s.name&&(o.errorType=s.name);const n=[];let a=s.cause;for(let e=0;e<3&&a;e++){const e=a,t="string"==typeof e.name&&e.name?e.name:void 0,r="string"==typeof e.message?e.message:String(a);n.push(t?`${t}: ${r}`:r),a=e.cause}n.length&&(o.cause=n.join(" <- "));let c=t;for(let e=0;e<=3&&c;e++){if("object"==typeof c){const e=r(c);if(Object.keys(e).length){Object.assign(o,e);break}}c=c.cause}return o}