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

package/dist/services/ManifestService.d.ts

@@ -0,0 +1,91 @@
+import { BreakManifest } from '../types/BreakManifest';
+import { ManifestRequestInterceptor, ManifestResponseInterceptor } from '../types/OptiViewAdsConfig';
+import { ManifestSignatureKey } from './manifestSignature';
+/** Narrow diagnostic sink so the service does not depend on the full diagnostics module. */
+export type ManifestDiagnose = (code: 'DA-MANIFEST-INTERCEPT-FAILED' | 'DA-MANIFEST-REQUEST-INTERCEPT-FAILED' | 'DA-MANIFEST-SIGNATURE-INVALID', message: string, context?: Record<string, unknown>) => void;
+/** Fetches, verifies, parses and polls break manifests. */
+/**
+ * Whole-request budget for one manifest fetch. Matches the Android OkHttp `callTimeout` and
+ * stays inside a typical 30s caller budget so the failure is a specific manifest error.
+ */
+export declare const MANIFEST_FETCH_TIMEOUT_MS = 15000;
+/**
+ * Evidence carried on every failed manifest read. Kept small so it is never sampled or dropped.
+ * `url` is the only field that shows a WRONG target (a base URL pointing at the API host 404s
+ * every manifest); `host` is what groups failures by origin. `hostOk`/`hostFail` (same host,
+ * same session) separate a dead backend from this client's path. No dns/connect/tls split: `fetch` cannot produce it.
+ */
+export interface ManifestFetchEvidence {
+    /** The exact URL that was read — the only field that shows a WRONG target. */
+    url: string;
+    /** Host of {@link url}, so failures can be grouped by origin. */
+    host: string;
+    /** How it failed: no answer, an HTTP error, or the connection itself. */
+    outcome: 'timeout' | 'http' | 'network';
+    /** HTTP status when a response arrived at all; omitted otherwise. */
+    status?: number;
+    /** Wall time spent on this attempt. */
+    ms: number;
+    /** Manifest reads to this host that SUCCEEDED earlier in this session. */
+    hostOk: number;
+    /** Manifest reads to this host that failed earlier in this session. */
+    hostFail: number;
+}
+export declare class ManifestService {
+    private manifestUrl;
+    private pollingInterval;
+    private pollingIntervalSeconds;
+    /** Current polling cadence, or null when not running. Bounds every latency measured against a poll. */
+    get currentPollingIntervalSeconds(): number | null;
+    private pollCallbacks;
+    private currentManifest;
+    private isActive;
+    private debug;
+    private interceptor;
+    private diagnose;
+    private requestInterceptor;
+    private trustedKeys;
+    /** Per-host tally of manifest reads this session, and the last failure. */
+    private readonly hostTally;
+    private lastFailure;
+    constructor(debug?: boolean, interceptor?: ManifestResponseInterceptor, diagnose?: ManifestDiagnose, requestInterceptor?: ManifestRequestInterceptor, trustedKeys?: readonly ManifestSignatureKey[]);
+    /**
+     * Evidence for the most recent failed read. Kept as a field rather than on the thrown error:
+     * `fetchWithTimeout` re-wraps a timeout into a new Error, and a field survives that on every platform.
+     */
+    takeLastFailure(): ManifestFetchEvidence | null;
+    /** Count an outcome against its host and, when it failed, keep the evidence. */
+    private record;
+    /** Must be called before fetchManifest() or startPolling(). */
+    setManifestUrl(url: string): void;
+    /** Fetch the manifest once. */
+    fetchManifest(): Promise<BreakManifest>;
+    /**
+     * Resolve the raw manifest body after the request interceptor (mock body, redirect, or
+     * headers). A thrown/rejected interceptor is non-fatal: diagnose and fetch the original URL.
+     */
+    private fetchManifestData;
+    /** The interceptor's manifest, or the original when none is set or it throws. */
+    private applyInterceptor;
+    /** Parse and validate via the shared pure parser. */
+    private parseManifest;
+    /**
+     * Cadence comes only from the manifest's `polling` object (`active` during a break, `idle`
+     * otherwise). Without one no timer starts; the manifest is fetched once per session.
+     */
+    startPolling(onUpdate: (manifest: BreakManifest) => void, onError: (error: Error) => void): void;
+    /** Stop polling for manifest updates. */
+    stopPolling(): void;
+    /** A running timer is cancelled and restarted with the interval the new state dictates. */
+    setActive(active: boolean): void;
+    /** Re-resolve the polling decision; a polled manifest may change or remove its `polling` object. */
+    private applyPollingDecision;
+    private clearPollingTimer;
+    /** Get the current manifest. */
+    getManifest(): BreakManifest | null;
+    /** Reset session state (manifest URL and cached manifest) before starting a new session. */
+    reset(): void;
+    /** Clean up resources. */
+    destroy(): void;
+    private log;
+}

package/dist/services/ManifestService.js

@@ -0,0 +1 @@
+import{fetchWithTimeout as t}from"./fetchWithTimeout";import{verifyManifestSignature as e,MANIFEST_SIGNATURE_HEADER as i}from"./manifestSignature";import{embeddedManifestKeys as s}from"./manifestTrustedKeys";import{parseBreakManifest as n}from"./parseBreakManifest";import{resolvePollingDecision as r}from"./resolvePollingDecision";import{debugLog as l}from"../diagnostics/debugLog";export const MANIFEST_FETCH_TIMEOUT_MS=15e3;export class ManifestService{get currentPollingIntervalSeconds(){return this.pollingIntervalSeconds}constructor(t=!1,e,i,n,r){this.manifestUrl=null,this.pollingInterval=null,this.pollingIntervalSeconds=null,this.pollCallbacks=null,this.currentManifest=null,this.isActive=!1,this.hostTally=new Map,this.lastFailure=null,this.debug=t,this.interceptor=e,this.diagnose=i,this.requestInterceptor=n,this.trustedKeys=r??s()}takeLastFailure(){const t=this.lastFailure;return this.lastFailure=null,t}record(t,e,i,s){const n=function(t){try{return new URL(t).host}catch{return t}}(t),r=this.hostTally.get(n)??{ok:0,fail:0};if("ok"===e)return r.ok++,void this.hostTally.set(n,r);this.lastFailure={url:t,host:n,outcome:e,ms:i,hostOk:r.ok,hostFail:r.fail,...void 0===s?{}:{status:s}},r.fail++,this.hostTally.set(n,r)}setManifestUrl(t){this.manifestUrl=t}async fetchManifest(){if(!this.manifestUrl)throw new Error("Manifest URL not set. Call setManifestUrl() before fetching.");this.log("Fetching manifest from:",this.manifestUrl);const t=await this.fetchManifestData(this.manifestUrl),e=this.parseManifest(t),i=await this.applyInterceptor(e);return this.currentManifest=i,this.log("Manifest loaded:",i.breaks.length,"breaks"),i}async fetchManifestData(s){const n={url:s};let r;if(this.requestInterceptor)try{r=await this.requestInterceptor({...n},{url:s})??void 0}catch(t){const e=t instanceof Error?t.message:String(t);this.diagnose?.("DA-MANIFEST-REQUEST-INTERCEPT-FAILED",e,{url:s}),this.log("Manifest request interceptor threw; using network fetch:",e),r=void 0}if(r&&"body"in r)return this.log("Manifest request interceptor returned a mock response (no network)"),"string"==typeof r.body?JSON.parse(r.body):r.body;const l=r??n,o=Date.now();let a;try{a=await t(l.url,l.headers?{headers:l.headers}:{},15e3,"Failed to fetch manifest: no response within 15000ms")}catch(t){const e=t instanceof Error&&t.message.includes("no response within");throw this.record(l.url,e?"timeout":"network",Date.now()-o),t}if(!a.ok)throw this.record(l.url,"http",Date.now()-o,a.status),new Error(`Failed to fetch manifest: ${a.status} ${a.statusText}`);this.record(l.url,"ok",Date.now()-o);const h=new Uint8Array(await a.arrayBuffer()),c=a.headers.get(i),f=e(c,h,this.trustedKeys);if(!f.valid){const t=`Manifest signature verification failed: ${f.reason}`;throw this.diagnose?.("DA-MANIFEST-SIGNATURE-INVALID",t,{url:l.url,reason:f.reason}),this.log("Rejecting manifest:",t),new Error(t)}return JSON.parse((new TextDecoder).decode(h))}async applyInterceptor(t){if(!this.interceptor)return t;const e=this.manifestUrl??"";try{return await this.interceptor(t,{url:e})}catch(i){const s=i instanceof Error?i.message:String(i);return this.diagnose?.("DA-MANIFEST-INTERCEPT-FAILED",s,{url:e}),this.log("Manifest interceptor threw; using un-modified manifest:",s),t}}parseManifest(t){return n(t)}startPolling(t,e){this.pollCallbacks={onUpdate:t,onError:e},this.applyPollingDecision()}stopPolling(){this.pollCallbacks=null,this.clearPollingTimer()}setActive(t){this.isActive!==t&&(this.isActive=t,this.log("Active state changed:",t),this.applyPollingDecision())}applyPollingDecision(){if(!this.pollCallbacks)return;const t=r(this.currentManifest?.polling,this.isActive);if("once"===t.mode)return this.pollingInterval&&this.log("Manifest has no polling object — fetch-once, stopping timer"),void this.clearPollingTimer();this.pollingInterval&&this.pollingIntervalSeconds===t.intervalSeconds||(this.clearPollingTimer(),this.log("Starting polling with interval:",t.intervalSeconds,"seconds"),this.pollingIntervalSeconds=t.intervalSeconds,this.pollingInterval=setInterval(async()=>{const t=this.pollCallbacks;if(t){try{const e=await this.fetchManifest();e.breaks.length>0&&this.log(`📡 Manifest: ${e.breaks.length} break(s)`),t.onUpdate(e)}catch(e){t.onError(e instanceof Error?e:new Error(String(e)))}this.applyPollingDecision()}},1e3*t.intervalSeconds))}clearPollingTimer(){this.pollingInterval&&(clearInterval(this.pollingInterval),this.pollingInterval=null,this.pollingIntervalSeconds=null,this.log("Polling stopped"))}getManifest(){return this.currentManifest}reset(){this.stopPolling(),this.currentManifest=null,this.manifestUrl=null,this.isActive=!1}destroy(){this.stopPolling(),this.currentManifest=null,this.manifestUrl=null}log(...t){this.debug&&l("[OptiViewAds:ManifestService]",...t)}}

package/dist/services/MetadataCueTracker.d.ts

@@ -0,0 +1,44 @@
+import type { TimedMetadataCue } from '../interfaces/PlayerAdapter';
+/** ID3 GEOB description of an Anvato break-signaling frame. */
+export declare const ANVATO_ID3_DESCRIPTION = "Anvatos";
+/** MIME type of Anvato GEOB frames; must match when surfaced, may be omitted by parsers that expose none. */
+export declare const ANVATO_ID3_MIME_TYPE = "application/json";
+/** DASH/CMAF emsg scheme id URI of an Anvato break-signaling event. */
+export declare const ANVATO_EMSG_SCHEME_ID_URI = "urn:anvato:es1:052016";
+/** Standardized "ID3 in emsg" schemes (CTA-5001 / Apple): message data is a complete raw ID3v2 tag. */
+export declare const ID3_IN_EMSG_SCHEME_ID_URIS: readonly string[];
+/** Returns true for the standardized ID3-in-emsg scheme id URIs. */
+export declare function isId3InEmsgScheme(schemeIdUri: string | undefined): boolean;
+/** Tolerance (seconds) matching a manifest `start` PTS to a cue `pts`; encoder/backend rounding differs sub-millisecond. */
+export declare const PTS_MATCH_TOLERANCE_SECONDS = 0.005;
+/** Anvato marker: GEOB with description "Anvatos" (MIME `application/json` when surfaced) or emsg with the Anvato scheme. */
+export declare function isAnvatoCue(cue: TimedMetadataCue): boolean;
+/**
+ * The Anvato payload (`type=cue&pts=…`) from an HLS ID3 GEOB cue, a direct Anvato emsg, or
+ * ID3-in-emsg (`raw` holds a complete ID3v2 tag); null when the cue is not Anvato signaling.
+ */
+export declare function anvatoPayloadFromCue(cue: TimedMetadataCue): string | null;
+/**
+ * Hand-written form-urlencoded parse so the Kotlin/Swift cores reproduce the exact semantics:
+ * split on `&`, then on the FIRST `=`, `+` as space, percent-decode, raw text on failure, first duplicate wins.
+ */
+export declare function parseAnvatoPayload(payload: string): Record<string, string>;
+/**
+ * Maps a break's manifest `pts` to the media time its Anvato cue was observed at. With
+ * `ptsSource: 'anvatoCue'` a PTS break is only schedulable once its cue was seen. Portable brain logic.
+ */
+export declare class MetadataCueTracker {
+    /** Observed cue `pts` parameter (seconds) → cue media time (seconds). */
+    private mediaTimeByPts;
+    /** Ignores non-Anvato cues, non-`type=cue` payloads, and non-finite `pts`. True when a cue was recorded or refreshed. */
+    handleCue(cue: TimedMetadataCue): boolean;
+    /**
+     * Media time of the cue matching `pts` within {@link PTS_MATCH_TOLERANCE_SECONDS}, or null.
+     * Closest wins; ties resolve to the lower cue PTS so the result is observation-order independent.
+     */
+    mediaTimeForPts(pts: number): number | null;
+    /** Number of distinct cue PTS values currently tracked. */
+    get size(): number;
+    /** Drop all tracked cues (session end / destroy). */
+    clear(): void;
+}

package/dist/services/MetadataCueTracker.js

@@ -0,0 +1 @@
+import{decodeUtf8 as e,parseId3GeobFrames as t}from"../id3/parseId3Geob";export const ANVATO_ID3_DESCRIPTION="Anvatos";export const ANVATO_ID3_MIME_TYPE="application/json";export const ANVATO_EMSG_SCHEME_ID_URI="urn:anvato:es1:052016";export const ID3_IN_EMSG_SCHEME_ID_URIS=["https://aomedia.org/emsg/ID3","https://developer.apple.com/streaming/emsg-id3"];export function isId3InEmsgScheme(e){return void 0!==e&&ID3_IN_EMSG_SCHEME_ID_URIS.includes(e)}export const PTS_MATCH_TOLERANCE_SECONDS=.005;export function isAnvatoCue(e){return"id3"===e.type?"Anvatos"===e.description&&(void 0===e.mimeType||"application/json"===e.mimeType):"emsg"===e.type&&"urn:anvato:es1:052016"===e.schemeIdUri}export function anvatoPayloadFromCue(n){if(isAnvatoCue(n))return n.messageData??null;if("emsg"===n.type&&isId3InEmsgScheme(n.schemeIdUri)&&n.raw)for(const o of t(n.raw))if("Anvatos"===o.description&&"application/json"===o.mimeType)return e(o.data);return null}export function parseAnvatoPayload(e){const t={};for(const o of e.split("&")){if(""===o)continue;const e=o.indexOf("="),i=-1===e?o:o.slice(0,e),s=-1===e?"":o.slice(e+1),r=n(i);r in t||(t[r]=n(s))}return t}function n(e){const t=e.replace(/\+/g," ");try{return decodeURIComponent(t)}catch{return t}}export class MetadataCueTracker{constructor(){this.mediaTimeByPts=new Map}handleCue(e){if(!Number.isFinite(e.startTime))return!1;const t=anvatoPayloadFromCue(e);if(!t)return!1;const n=parseAnvatoPayload(t);if("cue"!==n.type)return!1;const o=Number(n.pts);return!!Number.isFinite(o)&&(this.mediaTimeByPts.set(o,e.startTime),!0)}mediaTimeForPts(e){let t=null,n=1/0;for(const o of this.mediaTimeByPts.keys()){const i=Math.abs(o-e);i>.005||(i<n||i===n&&o<t)&&(t=o,n=i)}return null===t?null:this.mediaTimeByPts.get(t)}get size(){return this.mediaTimeByPts.size}clear(){this.mediaTimeByPts.clear()}}

package/dist/services/PauseAdController.d.ts

@@ -0,0 +1,108 @@
+import { Asset, Break, BreakManifest, MediaType } from '../types/BreakManifest';
+import { Clock } from './BreakScheduler';
+/** The resolved pause ad: `source` picks direct load (`static`) or VAST fetch (`vast`); `mediaType` picks image overlay or muted play-once `<video>`. */
+export interface PauseAdResolution {
+    /** The pause break (`start: { type: 'event', event: 'pause' }`). */
+    break: Break;
+    /** The first asset of the first variant (image or video). */
+    asset: Asset;
+    /** How the asset is sourced. */
+    source: 'static' | 'vast';
+    /** Whether the asset is an image or a video. */
+    mediaType: MediaType;
+}
+/** Fired when the pause ad should be shown. */
+export type PauseAdShowCallback = (resolution: PauseAdResolution) => void;
+/** Fired when the pause ad should be hidden (on resume or duration cap). */
+export type PauseAdHideCallback = (breakId: string) => void;
+/** Fired once per shown pause ad when the viewer may resume content (see {@link PauseAdController.canResume}). */
+export type PauseAdResumeAllowedCallback = (breakId: string) => void;
+/** Structured diagnostic sink. */
+export type PauseAdDiagnoseCallback = (code: 'DA-PAUSE-AD-SHOWN' | 'DA-PAUSE-AD-DISMISSED' | 'DA-PAUSE-AD-NO-ASSET' | 'DA-PAUSE-AD-RESUME-ALLOWED' | 'DA-PAUSE-AD-RESUME-BLOCKED', message: string, context?: Record<string, unknown>) => void;
+/**
+ * Event-driven pause-ad state machine (spec `EventTrigger` with `event: 'pause'`).
+ *
+ * Every pause consumes the next pause break in manifest order, wrapping to the first once the
+ * list is exhausted. The break's `start.delay` must elapse while still paused before it shows;
+ * `duration` caps the display. While shown, content may resume only once `controls.skipOffset`
+ * elapsed — or, without a skipOffset, once a video creative ended or an image reached its
+ * duration cap (an image with neither can be resumed at once, so the viewer is never locked).
+ *
+ * DOM-free and clock-injected so the conformance harness can step {@link tick}. Rendering, VAST
+ * fetching and tracking live in the render layer. SGAI-only (not constructed in SSAI mode).
+ */
+export declare class PauseAdController {
+    private clock;
+    private debug;
+    private onShow;
+    private onHide;
+    private onResumeAllowed;
+    private diagnose;
+    /** Pause breaks of the current manifest, in manifest order. */
+    private pauseBreaks;
+    /** Index into {@link pauseBreaks} of the break the next pause will consume. */
+    private nextIndex;
+    /** The ad currently shown, or null when hidden. */
+    private current;
+    /** Whether content is currently paused. */
+    private paused;
+    /** Clock time (ms) when the current pause began, or null when playing. */
+    private pausedAtMs;
+    /** Ad selected for the current pause, waiting for its `start.delay`; null once shown or when none is usable. */
+    private pending;
+    /** Clock time (ms) when the ad was shown, or null when hidden. */
+    private shownAtMs;
+    /** Whether resume has already been announced for the shown ad. */
+    private resumeAnnounced;
+    /** Whether the shown video creative ended (or cannot play). */
+    private creativeEnded;
+    constructor(options?: {
+        clock?: Clock;
+        debug?: boolean;
+    });
+    /** Register the show/hide/resume-allowed/diagnostic callbacks. */
+    setCallbacks(callbacks: {
+        onShow?: PauseAdShowCallback;
+        onHide?: PauseAdHideCallback;
+        onResumeAllowed?: PauseAdResumeAllowedCallback;
+        diagnose?: PauseAdDiagnoseCallback;
+    }): void;
+    /** Replace the pause-break list. A shown ad stays up; the rotation index is kept (wrapped). */
+    updateManifest(manifest: BreakManifest): void;
+    /** Notify the controller that content was paused (from the `pause` event). */
+    onPause(): void;
+    /**
+     * Notify the controller that content resumed (from the `playing` event). Returns false when the
+     * shown ad must still be watched ({@link canResume}); the caller then pauses content again and
+     * the ad stays up.
+     */
+    onResume(): boolean;
+    /** Arm-after-`delay` show, `skipOffset` reveal and `duration`-cap dismiss; periodic in production, stepped by the harness. */
+    tick(): void;
+    /** Whether the pause ad is currently shown. */
+    isShowing(): boolean;
+    /** Notify the controller that the shown video creative ended or cannot play (from the renderer). */
+    onCreativeEnded(breakId: string): void;
+    /**
+     * Whether the viewer may resume content now. Always true when no ad is shown. While shown:
+     * `controls.skipOffset` elapsed. Without a skipOffset the ad must be watched fully: a video
+     * until it ends, an image until the duration cap (no cap: at once).
+     */
+    canResume(): boolean;
+    private evaluate;
+    /**
+     * Next usable pause break in manifest order, starting at the rotation index and wrapping once.
+     * Unusable breaks are skipped (diagnosed) so they never swallow a pause.
+     */
+    private selectNext;
+    private resolve;
+    private show;
+    private announceResumeIfAllowed;
+    private hide;
+    /** Clear runtime state between sessions while keeping registered callbacks. */
+    reset(): void;
+    /** Clear all state (session end / destroy). */
+    destroy(): void;
+    private clearState;
+    private log;
+}

package/dist/services/PauseAdController.js

@@ -0,0 +1 @@
+import{AssetType as e,isEventTrigger as s,isPauseBreak as t,MediaType as n}from"../types/BreakManifest";import{systemClock as i}from"./BreakScheduler";import{debugLog as h}from"../diagnostics/debugLog";export class PauseAdController{constructor(e){this.onShow=null,this.onHide=null,this.onResumeAllowed=null,this.diagnose=null,this.pauseBreaks=[],this.nextIndex=0,this.current=null,this.paused=!1,this.pausedAtMs=null,this.pending=null,this.shownAtMs=null,this.resumeAnnounced=!1,this.creativeEnded=!1,this.clock=e?.clock??i,this.debug=e?.debug??!1}setCallbacks(e){this.onShow=e.onShow??null,this.onHide=e.onHide??null,this.onResumeAllowed=e.onResumeAllowed??null,this.diagnose=e.diagnose??null}updateManifest(e){this.pauseBreaks=e.breaks.filter(t),0===this.pauseBreaks.length?this.nextIndex=0:this.nextIndex%=this.pauseBreaks.length}onPause(){this.paused||(this.paused=!0,this.pausedAtMs=this.clock.now(),this.pending=this.selectNext(),this.log("content paused"),this.evaluate())}onResume(){if(!this.paused&&null===this.shownAtMs)return!0;if(null!==this.shownAtMs&&!this.canResume()){const e=this.current;return this.diagnose?.("DA-PAUSE-AD-RESUME-BLOCKED",`Pause ad "${e.break.id}" must still be watched; content stays paused.`,{breakId:e.break.id,elapsedSec:(this.clock.now()-this.shownAtMs)/1e3,skipOffset:e.break.controls?.skipOffset??null}),!1}return this.paused=!1,this.pausedAtMs=null,this.pending=null,this.hide("resume"),!0}tick(){this.evaluate()}isShowing(){return null!==this.shownAtMs}onCreativeEnded(e){null!==this.shownAtMs&&this.current?.break.id===e&&(this.creativeEnded=!0,this.announceResumeIfAllowed())}canResume(){if(null===this.shownAtMs||!this.current)return!0;const e=this.clock.now()-this.shownAtMs,s=this.current.break.controls?.skipOffset;if(void 0!==s)return e>=1e3*s;if(this.current.mediaType===n.VIDEO)return this.creativeEnded;const t=this.current.break.duration??0;return t<=0||e>=1e3*t}evaluate(){if(null!==this.shownAtMs&&this.current){const e=this.current.break.duration??0;return e>0&&this.clock.now()-this.shownAtMs>=1e3*e?void this.hide("duration"):void this.announceResumeIfAllowed()}if(!this.paused||null===this.pausedAtMs||!this.pending)return;const{index:e,resolution:t}=this.pending,{start:n}=t.break,i=s(n)&&n.delay||0;this.clock.now()-this.pausedAtMs<1e3*i||(this.pending=null,this.nextIndex=(e+1)%this.pauseBreaks.length,this.show(t))}selectNext(){const e=this.pauseBreaks.length;for(let s=0;s<e;s++){const t=(this.nextIndex+s)%e,n=this.resolve(this.pauseBreaks[t]);if(n)return{index:t,resolution:n}}return null}resolve(s){const t=Array.isArray(s.variant)?s.variant[0]:s.variant,i=(t?.assets??[])[0];if(!i||i.mediaType!==n.IMAGE&&i.mediaType!==n.VIDEO)return this.diagnose?.("DA-PAUSE-AD-NO-ASSET",`Pause break "${s.id}" has no image or video asset; skipping.`,{breakId:s.id}),null;return{break:s,asset:i,source:i.type===e.VAST?"vast":"static",mediaType:i.mediaType}}show(e){this.current=e,this.shownAtMs=this.clock.now(),this.resumeAnnounced=!1,this.creativeEnded=!1,this.log(`showing pause ad "${e.break.id}" (${e.source}, ${e.mediaType})`),this.diagnose?.("DA-PAUSE-AD-SHOWN",`Pause ad "${e.break.id}" shown.`,{breakId:e.break.id,source:e.source,mediaType:e.mediaType,skipOffset:e.break.controls?.skipOffset??null}),this.onShow?.(e),this.announceResumeIfAllowed()}announceResumeIfAllowed(){if(this.resumeAnnounced||!this.current||!this.canResume())return;this.resumeAnnounced=!0;const e=this.current.break.id;this.log(`pause ad "${e}" may be resumed`),this.diagnose?.("DA-PAUSE-AD-RESUME-ALLOWED",`Pause ad "${e}" may be resumed.`,{breakId:e}),this.onResumeAllowed?.(e)}hide(e){if(null===this.shownAtMs)return;const s=this.current?.break.id??"";this.shownAtMs=null,this.current=null,this.resumeAnnounced=!1,this.creativeEnded=!1,this.log(`hiding pause ad "${s}" (${e})`),this.diagnose?.("DA-PAUSE-AD-DISMISSED",`Pause ad "${s}" dismissed (${e}).`,{breakId:s,reason:e}),this.onHide?.(s)}reset(){this.clearState()}destroy(){this.clearState(),this.onShow=null,this.onHide=null,this.onResumeAllowed=null,this.diagnose=null}clearState(){this.pauseBreaks=[],this.nextIndex=0,this.current=null,this.paused=!1,this.pausedAtMs=null,this.pending=null,this.shownAtMs=null,this.resumeAnnounced=!1}log(...e){this.debug&&h("[PauseAdController]",...e)}}

package/dist/services/RewindRearm.d.ts

@@ -0,0 +1,109 @@
+import { BreakState } from './BreakScheduler';
+import type { Clock } from './BreakScheduler';
+import { Break } from '../types/BreakManifest';
+import type { BreakTimingState } from './breakTiming';
+export interface TrackedBreak {
+    break: Break;
+    state: BreakState;
+}
+export interface RewindRearmDeps {
+    breaks: Map<string, TrackedBreak>;
+    retiredBreaks: Map<string, Break>;
+    completedBreakIds: Set<string>;
+    preloadedBreakIds: Set<string>;
+    timing: BreakTimingState;
+    clock: Clock;
+    log: (...args: unknown[]) => void;
+    getBreakStartTime: (breakInfo: Break) => number | null;
+}
+export declare class RewindRearm {
+    private readonly deps;
+    /**
+     * `adStartDelay` in ms: played media time before ANY break may start. Breaks that pass during
+     * the delay are not started retroactively but stay unconsumed. Zero means no delay.
+     */
+    private _adStartDelayMs;
+    private adStartDelayElapsedLogged;
+    private adStartDelayIgnored;
+    private channelPlayedBaselineMs;
+    /** Set once content playback began this session (spec `event: 'start'`); pre-rolls wait for it. */
+    private _playbackStarted;
+    /**
+     * Played media time since playback start, shared by `adStartDelay` and pre-roll delays. Forward
+     * progress per tick is capped at the wallclock elapsed, so a paused player credits nothing and
+     * a seek credits at most one tick.
+     */
+    private _playedMs;
+    /** Timebase position (ms) at the previous played-time sample. */
+    private lastPlayedPositionMs;
+    /** Wallclock (ms) at the previous played-time sample. */
+    private lastPlayedClockMs;
+    /**
+     * Set while content is RELOADED rather than seeked (shared-element path). The playhead passes
+     * through ~0, which the rewind detector would read as a seek before the break and re-arm it;
+     * during a reload there is no meaningful previous position to compare against.
+     */
+    private contentReloading;
+    /**
+     * Guard for the SDK's own post-break resume-seek ({@link notifyResumeSeek}): a player may
+     * emit a seek adjustment after the target is accepted, so a backward step inside the finished
+     * break window is internal while armed. Cleared on the first forward sample.
+     */
+    private resumeSeekBaselineMs;
+    private resumeSeekBreakEndMs;
+    private resumeSeekInFlight;
+    /**
+     * Pre-step position of a backward step awaiting confirmation. A rewind counts only when two
+     * consecutive samples sit behind it: a single backward sample can be a transient (PiP
+     * hand-off, stale position mid-recovery).
+     */
+    private pendingRewindFromMs;
+    /** currentTime (ms) observed on the previous tick, for backward-seek detection. */
+    private lastCurrentTime;
+    /**
+     * Minimum backward step for a WALLCLOCK rewind to count as a DVR seek-back. Live PDT is
+     * fragment-anchored and jitters backward by fractions of a second, which would re-fire the
+     * break just watched. PTS positions are exact, so no jitter tolerance applies there.
+     */
+    private readonly REWIND_JITTER_TOLERANCE_MS;
+    constructor(deps: RewindRearmDeps);
+    /** While true no break may start and consumers must not apply break-driven restrictions (e.g. pause ads). */
+    isAdStartDelayActive(): boolean;
+    get playbackStarted(): boolean;
+    get playedMs(): number;
+    /** Anchor played-time tracking at the position where content playback began. */
+    markPlaybackStart(positionMs: number | null): void;
+    setAdStartDelayMs(ms: number): void;
+    /**
+     * The schedule now follows another channel: pre-roll `delay` counts from here. Once playback
+     * has started, `adStartDelay` is frozen (also for later polls); before that the next manifest's
+     * value applies.
+     */
+    beginChannel(): void;
+    /** Played time since the current channel took over (whole session for the first channel). */
+    get channelPlayedMs(): number;
+    get adStartDelayMs(): number;
+    /** Bracket a content RELOAD so the new stream's start is not read as a backward seek. `false` also discards the stale previous position. */
+    setContentReloading(active: boolean): void;
+    /**
+     * The runtime is about to resume-seek content to `targetSeconds` after a break ending at
+     * `breakEndSeconds`. Arms a guard so the small backward step is not read as a DVR seek-back;
+     * a genuine seek below the cue still re-arms. PTS timebase only (`seconds * 1000`).
+     */
+    notifyResumeSeek(targetSeconds: number, breakEndSeconds: number): void;
+    /** A viewer seek through the SDK: drop the resume-seek guard so the step is judged by the normal rules. */
+    notifyViewerSeek(): void;
+    /** Forward progress is capped at the wallclock elapsed: a paused player credits nothing, a seek at most one tick. */
+    trackPlayedTime(currentTime: number | null): void;
+    /**
+     * Re-arm retired position breaks when the playhead moves backward past their end (DVR seek
+     * back). Live breaks are untouched. A rewind needs TWO consecutive samples behind the
+     * pre-step position (see `pendingRewindFromMs`), so a one-sample transient never re-arms.
+     */
+    rearmOnRewind(currentTime: number): void;
+    reset(): void;
+    /** True when `currentTime` sits behind `from` by more than live PDT jitter. */
+    private isRewindBeyondJitter;
+    /** Confirmed DVR rewind: drop the resume guard and re-arm retired breaks. */
+    private rearmRetiredBreaks;
+}

package/dist/services/RewindRearm.js

@@ -0,0 +1 @@
+import{BreakState as e}from"./BreakScheduler";import{Timebase as s}from"../types/BreakManifest";export class RewindRearm{constructor(e){this.deps=e,this._adStartDelayMs=0,this.adStartDelayElapsedLogged=!1,this.adStartDelayIgnored=!1,this.channelPlayedBaselineMs=0,this._playbackStarted=!1,this._playedMs=0,this.lastPlayedPositionMs=null,this.lastPlayedClockMs=null,this.contentReloading=!1,this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null,this.resumeSeekInFlight=!1,this.pendingRewindFromMs=null,this.lastCurrentTime=null,this.REWIND_JITTER_TOLERANCE_MS=2e3}isAdStartDelayActive(){return this._adStartDelayMs>0&&this._playedMs<this._adStartDelayMs}get playbackStarted(){return this._playbackStarted}get playedMs(){return this._playedMs}markPlaybackStart(e){this._playbackStarted=!0,this.lastPlayedPositionMs=e,this.lastPlayedClockMs=this.deps.clock.now()}setAdStartDelayMs(e){this.adStartDelayIgnored||(this._adStartDelayMs=e)}beginChannel(){this.channelPlayedBaselineMs=this._playedMs,this._playbackStarted&&(this._adStartDelayMs=0,this.adStartDelayIgnored=!0)}get channelPlayedMs(){return this._playedMs-this.channelPlayedBaselineMs}get adStartDelayMs(){return this._adStartDelayMs}setContentReloading(e){this.contentReloading=e,e||(this.lastCurrentTime=null),this.pendingRewindFromMs=null}notifyResumeSeek(e,s){Number.isFinite(e)&&Number.isFinite(s)&&(this.resumeSeekBaselineMs=1e3*e,this.resumeSeekBreakEndMs=1e3*s,this.resumeSeekInFlight=!0,this.lastCurrentTime=this.resumeSeekBaselineMs,this.pendingRewindFromMs=null)}notifyViewerSeek(){this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null,this.resumeSeekInFlight=!1}trackPlayedTime(e){if(!this._playbackStarted)return;const s=this.deps.clock.now();if(null===e)return this.lastPlayedPositionMs=null,void(this.lastPlayedClockMs=s);if(null!==this.lastPlayedPositionMs&&null!==this.lastPlayedClockMs){const t=e-this.lastPlayedPositionMs,i=s-this.lastPlayedClockMs;this._playedMs+=Math.min(Math.max(0,t),Math.max(0,i)),this._adStartDelayMs>0&&this._playedMs>=this._adStartDelayMs&&!this.adStartDelayElapsedLogged&&(this.adStartDelayElapsedLogged=!0,this.deps.log(`⏰ Ad start delay elapsed (${this._adStartDelayMs/1e3}s played)`))}this.lastPlayedPositionMs=e,this.lastPlayedClockMs=s}rearmOnRewind(e){const s=this.lastCurrentTime;if(this.lastCurrentTime=e,null!==this.resumeSeekBreakEndMs&&e>this.resumeSeekBreakEndMs&&(this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null,this.resumeSeekInFlight=!1),this.contentReloading)this.pendingRewindFromMs=null;else{if(null!==this.pendingRewindFromMs){const s=this.pendingRewindFromMs;if(this.pendingRewindFromMs=null,this.isRewindBeyondJitter(s,e))return void this.rearmRetiredBreaks(e)}null===s||e>=s?this.resumeSeekInFlight&&null!==s&&e>s&&(this.resumeSeekInFlight=!1,this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null):this.isRewindBeyondJitter(s,e)&&(this.resumeSeekInFlight&&null!==this.resumeSeekBreakEndMs&&e>=0&&e<=this.resumeSeekBreakEndMs||(this.pendingRewindFromMs=s))}}reset(){this.lastCurrentTime=null,this._adStartDelayMs=0,this.adStartDelayElapsedLogged=!1,this._playbackStarted=!1,this._playedMs=0,this.adStartDelayIgnored=!1,this.channelPlayedBaselineMs=0,this.lastPlayedPositionMs=null,this.lastPlayedClockMs=null,this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null,this.resumeSeekInFlight=!1,this.pendingRewindFromMs=null}isRewindBeyondJitter(e,t){return!(t>=e)&&!(this.deps.timing.timebase===s.WALLCLOCK&&e-t<=this.REWIND_JITTER_TOLERANCE_MS)}rearmRetiredBreaks(s){if(this.resumeSeekBaselineMs=null,this.resumeSeekBreakEndMs=null,this.resumeSeekInFlight=!1,0!==this.deps.retiredBreaks.size)for(const[t,i]of[...this.deps.retiredBreaks]){const a=this.deps.breaks.get(t);if(a&&(a.state===e.PENDING||a.state===e.ACTIVE||a.state===e.CHAINED))continue;const l=this.deps.getBreakStartTime(i);if(null===l)continue;s<l+1e3*(i.duration??0)&&(this.deps.retiredBreaks.delete(t),this.deps.completedBreakIds.delete(t),this.deps.preloadedBreakIds.delete(t),this.deps.breaks.set(t,{break:i,state:e.PENDING}),this.deps.log(`↩️ Re-armed break "${t}" after backward seek`))}}}

package/dist/services/SsaiController.d.ts

@@ -0,0 +1,59 @@
+import type { PlayerAdapter } from '../interfaces/PlayerAdapter';
+import type { GamConfig, SsaiConfig, SsaiSessionConfig } from '../types/OptiViewAdsConfig';
+import type { StitchedStreamVendor } from './resolveDeliveryMode';
+import { AssetParameterMacros } from './assetParameterMacros';
+import type { OptiViewAdsEventMap, OptiViewAdsEventType } from '../types/Events';
+/** Org-level options the SSAI controller needs from the SDK config. */
+export interface SsaiControllerOptions {
+    gam: GamConfig;
+    /** SSAI has no break manifest, so its GAM identity is client-side. See SsaiConfig. */
+    ssai: SsaiConfig;
+    maxBitrate?: number | undefined;
+    autoplay?: boolean | undefined;
+    debug?: boolean | undefined;
+}
+/** Callbacks the controller uses to surface events/diagnostics back to the SDK. */
+export interface SsaiControllerCallbacks {
+    emit<T extends OptiViewAdsEventType>(event: T, data: OptiViewAdsEventMap[T]): void;
+    diagnose(code: string, message: string, context?: Record<string, unknown>): void;
+    log(...args: unknown[]): void;
+}
+/**
+ * Orchestrates Server-Side Ad Insertion: one pre-stitched stream on the CONTENT player. Creates
+ * an IMA DAI pod-serving session for a `stream_id`, loads the stitcher master URL, forwards
+ * `timedmetadata` to IMA for tracking, and re-emits IMA's ad lifecycle as SDK events. No
+ * manifest polling, scheduling, or ad-player overlay runs in this mode.
+ */
+export declare class SsaiController {
+    private readonly player;
+    private readonly options;
+    private readonly callbacks;
+    private gamStreamManager;
+    private readonly onTimedMetadata;
+    private breakCounter;
+    private adIndexInBreak;
+    private currentBreak;
+    private currentAsset;
+    private sessionConfigParameters;
+    private updatedParameters;
+    private manifestParameters;
+    private customerMacros;
+    constructor(player: PlayerAdapter, options: SsaiControllerOptions, callbacks: SsaiControllerCallbacks);
+    /** Create the IMA stream, load the stitched master, wire timed-metadata forwarding, optionally play. */
+    start(config: SsaiSessionConfig): Promise<void>;
+    /** Manifest-steered ssai: IMA `LiveStreamRequest` for the gam `assetKey`; IMA supplies the stream URL directly. */
+    startSteered(vendor: StitchedStreamVendor, sessionConfigParameters?: Record<string, string>, macros?: AssetParameterMacros): Promise<void>;
+    private resolveAdTagParameters;
+    updateAssetParameters(params: Record<string, string>): void;
+    setManifestAssetParameters(params: Record<string, string> | undefined): void;
+    /** Stop timed-metadata forwarding and destroy IMA. */
+    stop(): void;
+    /** Map IMA stream events onto SDK events with synthesized stable ids (no manifest entry exists). `totalAds` is 0 (unknown). */
+    private buildGamCallbacks;
+    private emitQuartile;
+    private ensureBreak;
+    /** Build a minimal synthetic Break for an SSAI ad pod. */
+    private synthBreak;
+    /** Build a minimal synthetic vendor-less Asset for an SSAI ad. */
+    private synthAsset;
+}

package/dist/services/SsaiController.js

@@ -0,0 +1 @@
+import{applyAssetParameterMacros as e,omitBreakScopedParameters as t}from"./assetParameterMacros";import{buildAssetParameterMacroTable as a}from"./assetParameterMacroTable";import{resolveAssetParameters as s}from"./resolveAssetParameters";import{AssetType as r,MediaType as i,BreakFormat as n}from"../types/BreakManifest";import{GamStreamManager as o}from"./GamStreamManager";import{resolveBreakFormat as m}from"./AdBreakSequencer";import{buildStitcherMasterUrl as d}from"./StitcherUrlBuilder";export class SsaiController{constructor(e,t,a){this.player=e,this.options=t,this.callbacks=a,this.gamStreamManager=null,this.breakCounter=0,this.adIndexInBreak=0,this.currentBreak=null,this.currentAsset=null,this.customerMacros={},this.onTimedMetadata=e=>{if(!e)return;const t=e;"presented"!==t.phase&&this.gamStreamManager?.processTimedMetadata(t)}}async start(e){const t=this.player.videoElement;if(!t)throw new Error("SSAI mode requires a content PlayerAdapter that exposes a videoElement (for IMA DAI).");if(!e.customAssetKey)throw new Error("SSAI mode requires a customAssetKey in startSession().");this.sessionConfigParameters=e.assetParameters,this.updatedParameters=void 0,this.manifestParameters=void 0,this.customerMacros={...e.assetParameterMacros};const a=new o(t,void 0,this.options.debug);a.setCallbacks(this.buildGamCallbacks()),this.gamStreamManager=a,await a.initialize({networkCode:this.options.ssai.networkCode,customAssetKey:e.customAssetKey,adTagParameters:this.resolveAdTagParameters(),streamActivityMonitorId:this.options.gam.streamActivityMonitorId});const s=a.getStreamId();if(!s)throw new Error("SSAI mode: IMA DAI session did not return a stream id.");const r=d({stitcherUrl:e.stitcherUrl,streamId:s,maxBitrate:this.options.maxBitrate});this.callbacks.log("SSAI stitched master URL:",r),this.player.on("timedmetadata",this.onTimedMetadata),await this.player.load(r),this.options.autoplay&&await this.player.play()}async startSteered(e,t,a){const s=this.player.videoElement;if(!s)throw new Error("SSAI mode requires a content PlayerAdapter that exposes a videoElement (for IMA DAI).");this.sessionConfigParameters=t,this.updatedParameters=void 0,this.manifestParameters=e.assetParameters,this.customerMacros={...a};const r=new o(s,void 0,this.options.debug);r.setCallbacks(this.buildGamCallbacks()),this.gamStreamManager=r;const i=await r.initializeLiveStream({assetKey:e.assetKey,networkCode:e.networkCode,adTagParameters:this.resolveAdTagParameters(),streamActivityMonitorId:this.options.gam.streamActivityMonitorId});this.callbacks.log("SSAI full-service DAI stream URL:",i),this.player.on("timedmetadata",this.onTimedMetadata),await this.player.load(i),this.options.autoplay&&await this.player.play()}resolveAdTagParameters(){const r=s(this.sessionConfigParameters,this.updatedParameters,this.manifestParameters,void 0),i=e(t(r),a({customerMacros:this.customerMacros,element:this.player.videoElement??null,breakDurationSec:void 0}));for(const{key:e,macro:t}of i.unresolved)this.callbacks.diagnose("DA-ASSET-MACRO-UNKNOWN",`Asset parameter '${e}' sent with literal macro '${t}': the macro has no value.`,{key:e,macro:t});return i.params}updateAssetParameters(e){this.updatedParameters=e,this.gamStreamManager?.replaceAdTagParameters(this.resolveAdTagParameters()??{})}setManifestAssetParameters(e){(function(e,t){e&&0===Object.keys(e).length&&(e=void 0);t&&0===Object.keys(t).length&&(t=void 0);if(e===t)return!0;if(!e||!t)return!1;const a=Object.keys(e);return a.length===Object.keys(t).length&&a.every(a=>e[a]===t[a])})(this.manifestParameters,e)||(this.manifestParameters=e,this.gamStreamManager&&(this.gamStreamManager.replaceAdTagParameters(this.resolveAdTagParameters()??{}),this.callbacks.diagnose("DA-ASSET-PARAMETERS-UPDATED","Manifest asset parameters changed; IMA targeting updated.",{source:"manifest",keys:Object.keys(e??{}).sort()})))}stop(){this.player.off("timedmetadata",this.onTimedMetadata),this.gamStreamManager?.destroy(),this.gamStreamManager=null,this.sessionConfigParameters=void 0,this.updatedParameters=void 0,this.manifestParameters=void 0,this.customerMacros={},this.currentBreak=null,this.currentAsset=null,this.breakCounter=0,this.adIndexInBreak=0}buildGamCallbacks(){return{onAdBreakStarted:()=>{this.breakCounter+=1,this.adIndexInBreak=0,this.currentBreak=this.synthBreak(`ssai-break-${this.breakCounter}`),this.callbacks.emit("adbreakbegin",{type:"adbreakbegin",timestamp:Date.now(),break:this.currentBreak,format:m(this.currentBreak),elapsedSec:0,remainingSec:this.currentBreak.duration})},onAdStarted:e=>{const t=this.ensureBreak(),a=this.adIndexInBreak;this.adIndexInBreak+=1,this.currentAsset=this.synthAsset(`${t.id}-ad-${this.adIndexInBreak}`),this.callbacks.emit("adbegin",{type:"adbegin",timestamp:Date.now(),break:t,format:m(t),asset:this.currentAsset,adIndex:a,totalAds:0,...void 0!==e?.adPosition&&Number.isInteger(e.adPosition)&&e.adPosition>=1?{podPosition:e.adPosition}:{}})},onAdFirstQuartile:()=>this.emitQuartile("adfirstquartile"),onAdMidpoint:()=>this.emitQuartile("admidpoint"),onAdThirdQuartile:()=>this.emitQuartile("adthirdquartile"),onAdComplete:()=>{const e=this.ensureBreak(),t=this.currentAsset??this.synthAsset(`${e.id}-ad`);this.callbacks.emit("adend",{type:"adend",timestamp:Date.now(),break:e,format:m(e),asset:t,adIndex:Math.max(0,this.adIndexInBreak-1),totalAds:0}),this.currentAsset=null},onAdBreakEnded:()=>{const e=this.ensureBreak();this.callbacks.emit("adbreakend",{type:"adbreakend",timestamp:Date.now(),break:e,format:m(e)}),this.currentBreak=null,this.currentAsset=null},onError:e=>{this.callbacks.diagnose("DA-SSAI-IMA-ERROR",e),this.callbacks.emit("aderror",{type:"aderror",timestamp:Date.now(),source:"ad",...this.currentBreak?{break:this.currentBreak,format:m(this.currentBreak)}:{},...this.currentAsset?{asset:this.currentAsset}:{},error:new Error(e)})}}}emitQuartile(e){const t=this.ensureBreak(),a=this.currentAsset??this.synthAsset(`${t.id}-ad`);this.callbacks.emit(e,{type:e,timestamp:Date.now(),break:t,format:m(t),asset:a})}ensureBreak(){return this.currentBreak||(this.breakCounter+=1,this.currentBreak=this.synthBreak(`ssai-break-${this.breakCounter}`)),this.currentBreak}synthBreak(e){return{id:e,start:this.player.currentTime,duration:0,variant:{format:n.SINGLE,assets:[]}}}synthAsset(e){return{id:e,type:r.STATIC,mediaType:i.VIDEO,uri:""}}}

package/dist/services/StitcherUrlBuilder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Inputs for building an SSAI stitcher master-playlist URL.
+ */
+export interface StitcherMasterUrlParams {
+    /**
+     * Full stitcher master-playlist URL as supplied by the caller, e.g.
+     * `https://stitch.example.com/ssai/v1/acme/sports/master.m3u8`. Used verbatim —
+     * the SDK only appends query parameters, never path segments.
+     */
+    stitcherUrl: string;
+    /** IMA DAI stream id obtained from the `GamStreamManager` session. */
+    streamId: string;
+    /**
+     * Optional maximum rendition bitrate (bits/sec). When set, the stitcher drops
+     * variants whose `BANDWIDTH` exceeds it from the returned master playlist.
+     */
+    maxBitrate?: number | undefined;
+    /** Extra query parameters to append (e.g. ad-tag passthrough). */
+    extraParams?: Record<string, string> | undefined;
+}
+/**
+ * Append the SSAI session parameters to the caller's stitcher master URL:
+ * `stream_id`, an optional `max_bitrate`, then any `extraParams` in insertion
+ * order. The stitcher uses `stream_id` to bind the stitched stream to the IMA
+ * DAI session so the in-stream ID3 metadata it injects can be matched back for
+ * ad tracking. Query keys/values are percent-encoded with {@link encodeRfc3986}.
+ *
+ * The caller's URL may already carry a query (a token, a tenant id), in which
+ * case the parameters are joined with `&`. A fragment is dropped: it is not sent
+ * to the server and would otherwise end up in the middle of the query string.
+ *
+ * @throws if any required field is missing/blank.
+ */
+export declare function buildStitcherMasterUrl(params: StitcherMasterUrlParams): string;

package/dist/services/StitcherUrlBuilder.js

@@ -0,0 +1 @@
+function r(r){return encodeURIComponent(r).replace(/[!'()*]/g,r=>"%"+r.charCodeAt(0).toString(16).toUpperCase())}export function buildStitcherMasterUrl(t){const{stitcherUrl:e,streamId:i,maxBitrate:n,extraParams:o}=t;if(!e)throw new Error("buildStitcherMasterUrl: stitcherUrl is required");if(!i)throw new Error("buildStitcherMasterUrl: streamId is required");const s=e.indexOf("#"),c=-1===s?e:e.slice(0,s),a=[`stream_id=${r(i)}`];if(void 0!==n&&a.push(`max_bitrate=${r(String(n))}`),o)for(const[t,e]of Object.entries(o))a.push(`${r(t)}=${r(e)}`);const d=c.includes("?")?"&":"?";return`${c}${d}${a.join("&")}`}

package/dist/services/VastAdManager.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Client-side (CSAI) VAST playout via the IMA HTML5 SDK (`google.ima`, loader `ima3.js`), as
+ * opposed to {@link GamStreamManager}'s DAI surface (`google.ima.dai.api`, `ima3_dai.js`). IMA
+ * fetches the VAST tag and owns the ad media in the SDK's overlay container for the ad's duration.
+ *
+ * @see https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side
+ */
+/** Ad-lifecycle callbacks surfaced to {@link AdPlayerController}. */
+export interface VastAdCallbacks {
+    /** `podPosition`: IMA's 1-based `getAdPodInfo().getAdPosition()` (carries the VAST `sequence`); undefined when none. */
+    onAdStarted?: (podPosition?: number) => void;
+    /** IMA does not drive the ad element's `timeupdate`, so this is the only progress signal for the break countdown. */
+    onAdProgress?: (currentTime: number, duration: number) => void;
+    onAdFirstQuartile?: () => void;
+    onAdMidpoint?: () => void;
+    onAdThirdQuartile?: () => void;
+    onContentPauseRequested?: () => void;
+    onContentResumeRequested?: () => void;
+}
+/** Whether `ima3.js` is present; the caller emits `DA-VAST-IMA-SDK-MISSING` when false. */
+export declare function isImaCsaiSdkAvailable(): boolean;
+/**
+ * One CSAI VAST playout at a time, reused across breaks. `preloadVast` then `startPreloaded`
+ * warms the ad before break start; `playVast()` is the single-shot path.
+ */
+export declare class VastAdManager {
+    private adContainer;
+    private adVideoElement;
+    private adDisplayContainer;
+    private adsLoader;
+    private adsManager;
+    private callbacks;
+    private debug;
+    private preloadResolve;
+    private preloadReject;
+    private startResolve;
+    private startReject;
+    private pendingMuted;
+    private settled;
+    private preloaded;
+    private started;
+    private currentAdDurationSec;
+    constructor(adContainer: HTMLElement, adVideoElement: HTMLVideoElement, debug?: boolean);
+    /** Set ad-lifecycle callbacks (replaces any previous set). */
+    setCallbacks(callbacks: VastAdCallbacks): void;
+    /**
+     * Resize the AdsManager to the ad element's current size. `preloadVast()` initialized IMA
+     * before the break layout existed, and a resize before `start()` is not always honoured (no
+     * renderer yet), so it runs again on IMA `STARTED` and on container resize.
+     */
+    resize(): void;
+    /** Fetch + parse + AdsManager init() with enablePreloading; does NOT call start(). Rejects on missing SDK or AD_ERROR. */
+    preloadVast(adTagUrl: string, options?: {
+        muted?: boolean;
+    }): Promise<void>;
+    /** Start a preloaded ad; resolves when all ads complete, rejects on AD_ERROR. */
+    startPreloaded(): Promise<void>;
+    /** Whether a preloaded ad is ready to start (else fall back to `playVast()`). */
+    hasPreloadedManager(): boolean;
+    /** Apply a mute change made between preload and play. */
+    setMuted(muted: boolean): void;
+    /** IMA CSAI drives ad audio through `AdsManager.setVolume()`, independent of the `<video>` volume. No-op without an AdsManager. */
+    setVolume(volume: number): void;
+    /** `preloadVast()` followed immediately by `startPreloaded()`. */
+    playVast(adTagUrl: string, options?: {
+        muted?: boolean;
+    }): Promise<void>;
+    private setupContainerAndLoader;
+    private onAdsManagerLoaded;
+    private wireManagerEvents;
+    /** `currentTime = duration − getRemainingTime()`; no-op until STARTED captured a duration. */
+    private emitAdProgress;
+    private onAdError;
+    private succeedStart;
+    private failStart;
+    private resolvePreload;
+    private rejectPreload;
+    private clearPreloadPromises;
+    private clearStartPromises;
+    private slotWidth;
+    private slotHeight;
+    /** Tear down only the per-playout IMA objects (keeps callbacks). */
+    private teardownManager;
+    /** Reset state before a new playout. Safe to call repeatedly. */
+    reset(): void;
+    /** Destroy the manager and drop callbacks. */
+    destroy(): void;
+    private log;
+}

package/dist/services/VastAdManager.js

@@ -0,0 +1 @@
+import{debugLog as e}from"../diagnostics/debugLog";import{VendorAdError as t}from"../types/VendorAdError";export function isImaCsaiSdkAvailable(){return"undefined"!=typeof google&&void 0!==google.ima&&void 0!==google.ima.AdsLoader&&void 0!==google.ima.AdDisplayContainer}export class VastAdManager{constructor(e,t,s=!1){this.adContainer=e,this.adVideoElement=t,this.adDisplayContainer=null,this.adsLoader=null,this.adsManager=null,this.callbacks={},this.preloadResolve=null,this.preloadReject=null,this.startResolve=null,this.startReject=null,this.pendingMuted=!1,this.settled=!1,this.preloaded=!1,this.started=!1,this.currentAdDurationSec=null,this.debug=s}setCallbacks(e){this.callbacks=e}resize(){this.adsManager&&(this.adsManager.resize(this.slotWidth(),this.slotHeight(),google.ima.ViewMode.NORMAL),this.log("VAST AdsManager resized to",this.slotWidth(),"x",this.slotHeight()))}preloadVast(e,t){return this.reset(),isImaCsaiSdkAvailable()?new Promise((s,a)=>{this.preloadResolve=s,this.preloadReject=a;try{this.setupContainerAndLoader();const s=new google.ima.AdsRequest;s.adTagUrl=e,s.linearAdSlotWidth=this.slotWidth(),s.linearAdSlotHeight=this.slotHeight(),s.setAdWillAutoPlay(!0),this.pendingMuted=t?.muted??!1,s.setAdWillPlayMuted(this.pendingMuted),this.log("Preloading VAST ads:",e),this.adsLoader.requestAds(s)}catch(e){this.rejectPreload(e instanceof Error?e:new Error(String(e)))}}):Promise.reject(new Error('Google IMA client-side SDK not found. Include <script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"><\/script> in your page.'))}startPreloaded(){return new Promise((e,t)=>{if(this.adsManager&&this.preloaded&&!this.started){this.started=!0,this.settled=!1,this.startResolve=e,this.startReject=t;try{this.resize(),this.adsManager.start(),this.log("VAST AdsManager started")}catch(e){this.failStart(e instanceof Error?e:new Error(String(e)))}}else t(new Error("No preloaded VAST AdsManager; call preloadVast() first"))})}hasPreloadedManager(){return null!==this.adsManager&&this.preloaded&&!this.started&&!this.settled}setMuted(e){this.pendingMuted=e,this.adsManager?.setVolume(e?0:1)}setVolume(e){this.pendingMuted=e<=0,this.adsManager?.setVolume(e)}playVast(e,t){return this.preloadVast(e,t).then(()=>this.startPreloaded())}setupContainerAndLoader(){this.adDisplayContainer=new google.ima.AdDisplayContainer(this.adContainer,this.adVideoElement),this.adDisplayContainer.initialize(),this.adsLoader=new google.ima.AdsLoader(this.adDisplayContainer),this.adsLoader.addEventListener(google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,e=>this.onAdsManagerLoaded(e)),this.adsLoader.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR,e=>this.onAdError(e))}onAdsManagerLoaded(e){try{const t=new google.ima.AdsRenderingSettings;t.restoreCustomPlaybackStateOnAdBreakComplete=!0,t.enablePreloading=!0;const s=e.getAdsManager(this.adVideoElement,t);this.adsManager=s,this.wireManagerEvents(s),this.pendingMuted&&s.setVolume(0),s.init(this.slotWidth(),this.slotHeight(),google.ima.ViewMode.NORMAL),this.preloaded=!0,this.resolvePreload(),this.log("VAST AdsManager initialized and ready")}catch(e){this.rejectPreload(e instanceof Error?e:new Error(String(e)))}}wireManagerEvents(e){const t=google.ima.AdEvent.Type;e.addEventListener(t.STARTED,e=>{this.resize();const t=e.getAd?.(),s=t?.getDuration?.();this.currentAdDurationSec="number"==typeof s&&Number.isFinite(s)&&s>0?s:null;const a=t?.getAdPodInfo?.()?.getAdPosition?.();this.callbacks.onAdStarted?.("number"==typeof a&&Number.isFinite(a)&&a>=1?Math.floor(a):void 0)}),e.addEventListener(t.AD_PROGRESS,()=>this.emitAdProgress()),e.addEventListener(t.FIRST_QUARTILE,()=>this.callbacks.onAdFirstQuartile?.()),e.addEventListener(t.MIDPOINT,()=>this.callbacks.onAdMidpoint?.()),e.addEventListener(t.THIRD_QUARTILE,()=>this.callbacks.onAdThirdQuartile?.()),e.addEventListener(t.CONTENT_PAUSE_REQUESTED,()=>this.callbacks.onContentPauseRequested?.()),e.addEventListener(t.CONTENT_RESUME_REQUESTED,()=>this.callbacks.onContentResumeRequested?.()),e.addEventListener(t.ALL_ADS_COMPLETED,()=>this.succeedStart()),e.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR,e=>this.onAdError(e))}emitAdProgress(){if(!this.callbacks.onAdProgress||!this.adsManager)return;const e=this.currentAdDurationSec;if(null==e)return;const t=this.adsManager.getRemainingTime();if(!Number.isFinite(t)||t<0)return;const s=Math.max(0,Math.min(e,e-t));this.callbacks.onAdProgress(s,e)}onAdError(e){const s=e?.getError?.(),a=s?.getMessage?.()??"Unknown IMA CSAI error",i=s?.getErrorCode?.();this.log("VAST IMA error:",a);const r="number"==typeof i?new t(a,String(i)):new Error(a);this.startReject?this.failStart(r):this.preloadReject&&this.rejectPreload(r)}succeedStart(){this.settled||(this.settled=!0,this.log("VAST playout complete"),this.startResolve?.(),this.clearStartPromises(),this.teardownManager())}failStart(e){this.settled||(this.settled=!0,this.startReject?.(e),this.clearStartPromises(),this.teardownManager())}resolvePreload(){this.preloadResolve?.(),this.clearPreloadPromises()}rejectPreload(e){this.preloadReject?.(e),this.clearPreloadPromises(),this.teardownManager()}clearPreloadPromises(){this.preloadResolve=null,this.preloadReject=null}clearStartPromises(){this.startResolve=null,this.startReject=null}slotWidth(){return this.adVideoElement.clientWidth||640}slotHeight(){return this.adVideoElement.clientHeight||360}teardownManager(){this.adsManager&&(this.adsManager.destroy(),this.adsManager=null),this.adsLoader&&(this.adsLoader.destroy(),this.adsLoader=null),this.adDisplayContainer&&(this.adDisplayContainer.destroy(),this.adDisplayContainer=null)}reset(){this.teardownManager(),this.settled=!1,this.preloaded=!1,this.started=!1,this.pendingMuted=!1,this.currentAdDurationSec=null,this.clearPreloadPromises(),this.clearStartPromises()}destroy(){this.reset(),this.callbacks={}}log(...t){this.debug&&e("[VastAdManager]",...t)}}