@streamlayer/feature-advertisement 1.0.0 → 1.1.1-rc.10.p6eb7304a

package/lib/cjs/units/ssai-log.d.ts

@@ -0,0 +1,16 @@
+import { type Logger } from '@streamlayer/sdk-web-logger';
+/**
+ * `ssaiq` — the SSAI ad NARRATIVE log: one line per thing that happens to a
+ * server-stitched ad, in the order it happens. The manifest tag the playout
+ * published, the metadata round trip it triggers, the break the SDK opens from
+ * it, and every beacon fired against it.
+ *
+ * Named for the Quortex/Synamedia DAI integration it was built for, but it is
+ * the path itself that is logged, so a StreamLayer-dialect stream tells the same
+ * story. Detector internals — clock sources, poll ticks, fold bookkeeping — stay
+ * on `ssai:*`, where `SL_DEBUG` can reach them without filling a demo window.
+ *
+ * A host publishes it to the page with `SL_LOG_EVENTS=ssaiq` (see
+ * `sdk-web-logger`); the demo's log window renders exactly that.
+ */
+export declare const ssaiq: Logger;

package/lib/cjs/units/ssai-log.js

@@ -0,0 +1,23 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+
+/**
+ * `ssaiq` — the SSAI ad NARRATIVE log: one line per thing that happens to a
+ * server-stitched ad, in the order it happens. The manifest tag the playout
+ * published, the metadata round trip it triggers, the break the SDK opens from
+ * it, and every beacon fired against it.
+ *
+ * Named for the Quortex/Synamedia DAI integration it was built for, but it is
+ * the path itself that is logged, so a StreamLayer-dialect stream tells the same
+ * story. Detector internals — clock sources, poll ticks, fold bookkeeping — stay
+ * on `ssai:*`, where `SL_DEBUG` can reach them without filling a demo window.
+ *
+ * A host publishes it to the page with `SL_LOG_EVENTS=ssaiq` (see
+ * `sdk-web-logger`); the demo's log window renders exactly that.
+ */
+// Explicit type: the inferred pino type is not nameable across package
+// boundaries (TS2742) when this file is compiled on its own.
+const ssaiq = sdkWebLogger.createLogger('ssaiq');
+
+exports.ssaiq = ssaiq;

package/lib/cjs/units/ssai-preload.d.ts

@@ -0,0 +1,20 @@
+import type { SsaiCreative } from './ssai-creative.js';
+/**
+ * How long the overlay is willing to wait for artwork. A slow or dead image host
+ * must never hold the bar back — the ad is already playing, and a bar that shows
+ * late is worse than one that shows without its logo (the logo is hidden on error
+ * anyway). Warming the browser cache is the goal; blocking is not.
+ */
+export declare const DEFAULT_PRELOAD_TIMEOUT_MS = 2000;
+/**
+ * Fetch images into the browser cache and resolve once they are all settled, or
+ * once `timeoutMs` elapses — whichever comes first. Never rejects: a creative
+ * whose artwork fails is still a creative worth showing.
+ */
+export declare const preloadImages: (urls: (string | undefined | null)[], timeoutMs?: number) => Promise<void>;
+/**
+ * Warm every image the creative carries — the overlay's brand logo, and the
+ * companion banner for hosts that render one — so the bar fades in complete
+ * rather than popping its artwork in a beat later.
+ */
+export declare const preloadCreativeAssets: (creative: SsaiCreative, timeoutMs?: number) => Promise<void>;

package/lib/cjs/units/ssai-preload.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+
+const log = sdkWebLogger.createLogger('ssai:preload');
+/**
+ * How long the overlay is willing to wait for artwork. A slow or dead image host
+ * must never hold the bar back — the ad is already playing, and a bar that shows
+ * late is worse than one that shows without its logo (the logo is hidden on error
+ * anyway). Warming the browser cache is the goal; blocking is not.
+ */
+const DEFAULT_PRELOAD_TIMEOUT_MS = 2000;
+/**
+ * Fetch images into the browser cache and resolve once they are all settled, or
+ * once `timeoutMs` elapses — whichever comes first. Never rejects: a creative
+ * whose artwork fails is still a creative worth showing.
+ */
+const preloadImages = (urls, timeoutMs = DEFAULT_PRELOAD_TIMEOUT_MS) => {
+    const targets = urls.filter((url) => !!url);
+    // `Image` is absent in SSR/worker contexts; there is nothing to warm there.
+    if (targets.length === 0 || typeof Image === 'undefined') {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let remaining = targets.length;
+        const finish = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            log.debug({ remaining }, 'ssai preload timed out, showing anyway');
+            finish();
+        }, timeoutMs);
+        const one = () => {
+            remaining -= 1;
+            if (remaining <= 0) {
+                finish();
+            }
+        };
+        for (const url of targets) {
+            const image = new Image();
+            image.onload = one;
+            image.onerror = one;
+            image.src = url;
+        }
+    });
+};
+/**
+ * Warm every image the creative carries — the overlay's brand logo, and the
+ * companion banner for hosts that render one — so the bar fades in complete
+ * rather than popping its artwork in a beat later.
+ */
+const preloadCreativeAssets = (creative, timeoutMs) => preloadImages([creative.iconUrl, creative.companion?.staticResource], timeoutMs);
+
+exports.DEFAULT_PRELOAD_TIMEOUT_MS = DEFAULT_PRELOAD_TIMEOUT_MS;
+exports.preloadCreativeAssets = preloadCreativeAssets;
+exports.preloadImages = preloadImages;

package/lib/cjs/units/ssai-providers.d.ts

@@ -0,0 +1,117 @@
+import type { SsaiCreative } from './ssai-creative.js';
+export declare const DEFAULT_CREATIVE_API_BASE = "https://hls.next.streamlayer.io/api/creatives/";
+/**
+ * A creative provider encapsulates everything that differs between ad sources:
+ * how a creativeId resolves to the normalized {@link SsaiCreative}, and how
+ * impressions (and, in the future, other tracking events) are fired. The overlay
+ * UI only ever sees the normalized shape, so it never learns about providers.
+ */
+export interface SsaiCreativeProvider {
+    /** Stable id for logging/diagnostics, e.g. 'streamlayer' | 'vast'. */
+    readonly id: string;
+    /** Resolve a creativeId (from EXT-X-DATERANGE) to the normalized SsaiCreative. */
+    resolve(creativeId: string, signal: AbortSignal): Promise<SsaiCreative>;
+    /**
+     * Fire an impression for a resolved creative. Provider-specific (URL shape,
+     * beacon vs pixel vs SDK call). Optional — falls back to the shared default
+     * (first trackingEvent named 'impression' via sendBeacon/fetch) when omitted.
+     */
+    fireImpression?(creative: SsaiCreative): void;
+    /** Optional hook for other tracking events (click, quartiles) — future-facing, no-op default. */
+    fireTracking?(creative: SsaiCreative, event: string): void;
+}
+/**
+ * Shared low-level beacon helper. Prefers `navigator.sendBeacon` and falls back
+ * to a no-cors `fetch`. Used by the default impression path and available to
+ * providers that fire URL-based tracking pixels.
+ */
+export declare const fireBeacon: (url: string) => void;
+/**
+ * Fire every tracking event with the given name, and report how many went out.
+ *
+ * ALL matches, not the first: the creative contract states that a creative may
+ * repeat an `event` value to carry several URLs, and that consumers must not
+ * assume uniqueness. Today's payloads carry one URL per event, so this is not a
+ * change in what goes on the wire — it just stops being wrong the day a server
+ * sends two.
+ */
+export declare const fireTrackingEvents: (creative: SsaiCreative, event: string) => number;
+/**
+ * Shared default impression behavior: fire the `impression` tracking events.
+ * Used by the StreamLayer provider and as the fallback in
+ * {@link SsaiCreativeCache} when a provider doesn't override `fireImpression`.
+ * Exported so both call sites share one definition.
+ */
+export declare const fireDefaultImpression: (creative: SsaiCreative) => void;
+export type StreamLayerProviderConfig = {
+    /** Base URL of the StreamLayer JSON creative metadata API. */
+    creativeApiBase?: string;
+};
+/**
+ * StreamLayer's internal creative provider. Resolves creatives from the JSON
+ * creative API (`GET {creativeApiBase}{encodeURIComponent(creativeId)}`) and
+ * fires impressions from the `'impression'` tracking event via `sendBeacon`.
+ */
+export declare const createStreamLayerProvider: (config?: StreamLayerProviderConfig) => SsaiCreativeProvider;
+export type QuortexProviderConfig = {
+    /**
+     * Full URL of the tenant's ad metadata endpoint, e.g.
+     * `https://ads.example.com/get_ad` or, with the tenant baked in,
+     * `https://ads.example.com/get_ad?TenantName=acme`. Required — this is
+     * customer infrastructure, so there is no sensible SDK-level default.
+     */
+    adApiBase?: string;
+    /**
+     * Tenant the ad ids belong to, appended as the `TenantName` query parameter.
+     * Optional: omit it when `adApiBase` already carries the tenant.
+     */
+    tenantName?: string;
+};
+/**
+ * Quortex / Synamedia DAI ad metadata provider.
+ *
+ * `GET {adApiBase}?TenantName={tenantName}&adID={adId}&info=1` (the `TenantName`
+ * part omitted when `adApiBase` already carries it) — the ad id comes
+ * from the manifest's `X-AD-ID` DATERANGE attribute (see `ssai-detector.ts`, which
+ * reconstructs the ad window from the tracking-marker burst those tags form).
+ *
+ * The response is byte-compatible with the StreamLayer creative API, so the same
+ * `mapApiResponse` normalizes both.
+ *
+ * Known limitation: impressions fire the `impression` tracking event from the API
+ * response, not the per-session beacon the manifest carries in `X-AD-URL`. The two
+ * differ in `trackingid`/`USERID`, so Quortex-side attribution will see the
+ * generic id rather than the viewer's session until the manifest beacons are
+ * plumbed through to the provider.
+ */
+export declare const createQuortexProvider: (config?: QuortexProviderConfig) => SsaiCreativeProvider;
+export type VastProviderConfig = Record<string, never>;
+/**
+ * Maps a VAST tag into the normalized SsaiCreative shape.
+ *
+ * Note: `fireImpression` is intentionally left to the shared default for now.
+ * Proper VAST impression/tracking wiring through `VASTTracker` is a documented
+ * follow-up; it requires retaining the parsed ad/tracker per creative.
+ */
+export declare const createVastProvider: (_config?: VastProviderConfig) => SsaiCreativeProvider;
+export type SsaiProviderName = 'streamlayer' | 'quortex' | 'vast';
+/** Union of every built-in provider's config; each factory reads its own keys. */
+export type SsaiProviderConfig = StreamLayerProviderConfig & QuortexProviderConfig;
+/** Built-in provider factories keyed by name. */
+export declare const BUILTIN_PROVIDERS: Record<SsaiProviderName, (config?: SsaiProviderConfig) => SsaiCreativeProvider>;
+export type SsaiProviderOption = 
+/** A ready provider instance (built-in or fully custom). */
+SsaiCreativeProvider
+/** A built-in provider selected by name. */
+ | SsaiProviderName
+/** A built-in provider selected by name with optional config. */
+ | {
+    name: SsaiProviderName;
+    config?: SsaiProviderConfig;
+};
+/**
+ * Resolve a {@link SsaiProviderOption} into a concrete {@link SsaiCreativeProvider}.
+ * Defaults to the StreamLayer provider (using `fallbackConfig`) when no option is
+ * supplied.
+ */
+export declare const resolveProvider: (option?: SsaiProviderOption, fallbackConfig?: SsaiProviderConfig) => SsaiCreativeProvider;

package/lib/cjs/units/ssai-providers.js

@@ -0,0 +1,300 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+var vastClient = require('@dailymotion/vast-client');
+var ssaiLog = require('./ssai-log.js');
+
+const log = sdkWebLogger.createLogger('ssai:provider');
+const DEFAULT_CREATIVE_API_BASE = 'https://hls.next.streamlayer.io/api/creatives/';
+/**
+ * One creative-metadata round trip, on the narrative log: the request the SDK
+ * made and the body the ad service answered with, verbatim. This is the half of
+ * the story the manifest cannot tell — the ad's identity comes from the playout,
+ * its content comes from here.
+ */
+const fetchCreativeJson = async (providerId, url, signal) => {
+    // `adApiBase` is customer infrastructure and may carry a key in its query;
+    // the request uses the URL as given, the log gets it with such values masked.
+    const shown = maskUrlSecrets(url);
+    ssaiLog.ssaiq.info({ provider: providerId, url: shown }, `[GET] → ${shown}`);
+    let response;
+    try {
+        response = await fetch(url, { signal });
+    }
+    catch (error) {
+        // An abort is the SDK cancelling its own request (break ended, creative
+        // changed) — a note, not a failure.
+        if (error?.name === 'AbortError') {
+            ssaiLog.ssaiq.debug({ provider: providerId, url: shown }, `[GET] ✗ aborted ${shown}`);
+        }
+        else {
+            ssaiLog.ssaiq.warn({ provider: providerId, url: shown, error: String(error) }, `[GET] ✗ ${shown}`);
+        }
+        throw error;
+    }
+    if (!response.ok) {
+        ssaiLog.ssaiq.warn({ provider: providerId, url: shown, status: response.status }, `[GET] ✗ ${response.status} ${shown}`);
+        throw new Error(`${providerId} creative request failed: ${response.status}`);
+    }
+    let raw;
+    try {
+        raw = (await response.json());
+    }
+    catch (error) {
+        // A 200 with a body that is not JSON would otherwise leave the log looking
+        // like a request still in flight.
+        ssaiLog.ssaiq.warn({ provider: providerId, url: shown, error: String(error) }, `[GET] ✗ ${response.status} ${shown} — not JSON`);
+        throw error;
+    }
+    ssaiLog.ssaiq.info({ provider: providerId, status: response.status, body: raw }, `[GET] ← ${response.status} ad metadata — ${raw?.advertiser || raw?.title || raw?.creativeId || 'ad'}`);
+    return raw;
+};
+/** `?apiKey=…` → `?apiKey=«redacted»`, for URLs that go on a screen. Regex, not `URL`: this ships to 2016 TV engines. */
+const maskUrlSecrets = (url) => url.replace(/([?&][^=&]*(?:token|secret|password|key|authorization)[^=&]*=)[^&]*/gi, '$1«redacted»');
+/**
+ * Shared low-level beacon helper. Prefers `navigator.sendBeacon` and falls back
+ * to a no-cors `fetch`. Used by the default impression path and available to
+ * providers that fire URL-based tracking pixels.
+ */
+const fireBeacon = (url) => {
+    try {
+        if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+            navigator.sendBeacon(url);
+        }
+        else {
+            void fetch(url, { mode: 'no-cors' }).catch((error) => {
+                log.warn(error, 'ssai beacon failed');
+            });
+        }
+    }
+    catch (error) {
+        log.warn(error, 'ssai beacon failed');
+    }
+};
+const resolveAdvertiser = (advertiser, title) => {
+    if (advertiser) {
+        return advertiser;
+    }
+    if (title) {
+        return title;
+    }
+    return 'Ad';
+};
+const buildCreativeUrl = (base, creativeId) => {
+    const normalizedBase = base.endsWith('/') ? base : `${base}/`;
+    return `${normalizedBase}${encodeURIComponent(creativeId)}`;
+};
+const mapApiResponse = (raw) => {
+    const trackingEvents = Array.isArray(raw.trackingEvents)
+        ? raw.trackingEvents
+            .filter((entry) => Boolean(entry?.event && entry?.url))
+            .map((entry) => ({ event: entry.event, url: entry.url }))
+        : [];
+    const rawCompanion = Array.isArray(raw.companions)
+        ? raw.companions.find((entry) => !!entry?.staticResource)
+        : undefined;
+    const companion = rawCompanion?.staticResource
+        ? {
+            staticResource: rawCompanion.staticResource,
+            width: Number(rawCompanion.width) || 0,
+            height: Number(rawCompanion.height) || 0,
+            clickThrough: rawCompanion.clickThrough,
+            clickTracking: Array.isArray(rawCompanion.clickTracking)
+                ? rawCompanion.clickTracking.filter((url) => typeof url === 'string' && !!url)
+                : [],
+        }
+        : undefined;
+    return {
+        creativeId: raw.creativeId,
+        advertiser: resolveAdvertiser(raw.advertiser, raw.title),
+        title: raw.title || resolveAdvertiser(raw.advertiser, raw.title),
+        iconUrl: raw.iconUrl || undefined,
+        clickThroughUrl: raw.clickThroughUrl || undefined,
+        trackingEvents,
+        companion,
+    };
+};
+/**
+ * Fire every tracking event with the given name, and report how many went out.
+ *
+ * ALL matches, not the first: the creative contract states that a creative may
+ * repeat an `event` value to carry several URLs, and that consumers must not
+ * assume uniqueness. Today's payloads carry one URL per event, so this is not a
+ * change in what goes on the wire — it just stops being wrong the day a server
+ * sends two.
+ */
+const fireTrackingEvents = (creative, event) => {
+    const matches = creative.trackingEvents.filter((entry) => entry.event === event);
+    for (const match of matches) {
+        fireBeacon(match.url);
+    }
+    return matches.length;
+};
+/**
+ * Shared default impression behavior: fire the `impression` tracking events.
+ * Used by the StreamLayer provider and as the fallback in
+ * {@link SsaiCreativeCache} when a provider doesn't override `fireImpression`.
+ * Exported so both call sites share one definition.
+ */
+const fireDefaultImpression = (creative) => {
+    fireTrackingEvents(creative, 'impression');
+};
+/**
+ * StreamLayer's internal creative provider. Resolves creatives from the JSON
+ * creative API (`GET {creativeApiBase}{encodeURIComponent(creativeId)}`) and
+ * fires impressions from the `'impression'` tracking event via `sendBeacon`.
+ */
+const createStreamLayerProvider = (config = {}) => {
+    const creativeApiBase = config.creativeApiBase ?? DEFAULT_CREATIVE_API_BASE;
+    return {
+        id: 'streamlayer',
+        resolve: async (creativeId, signal) => {
+            const raw = await fetchCreativeJson('streamlayer', buildCreativeUrl(creativeApiBase, creativeId), signal);
+            return mapApiResponse({ ...raw, creativeId: raw.creativeId || creativeId });
+        },
+        fireImpression: fireDefaultImpression,
+    };
+};
+const buildQuortexUrl = (base, tenantName, adId) => {
+    // Deliberately string concatenation rather than `URL`/`URLSearchParams`: this
+    // package ships to 2016-era TV engines (see the chrome-32 classic build).
+    const separator = base.indexOf('?') === -1 ? '?' : '&';
+    const tenant = tenantName ? `TenantName=${encodeURIComponent(tenantName)}&` : '';
+    return `${base}${separator}${tenant}adID=${encodeURIComponent(adId)}&info=1`;
+};
+/**
+ * Quortex / Synamedia DAI ad metadata provider.
+ *
+ * `GET {adApiBase}?TenantName={tenantName}&adID={adId}&info=1` (the `TenantName`
+ * part omitted when `adApiBase` already carries it) — the ad id comes
+ * from the manifest's `X-AD-ID` DATERANGE attribute (see `ssai-detector.ts`, which
+ * reconstructs the ad window from the tracking-marker burst those tags form).
+ *
+ * The response is byte-compatible with the StreamLayer creative API, so the same
+ * `mapApiResponse` normalizes both.
+ *
+ * Known limitation: impressions fire the `impression` tracking event from the API
+ * response, not the per-session beacon the manifest carries in `X-AD-URL`. The two
+ * differ in `trackingid`/`USERID`, so Quortex-side attribution will see the
+ * generic id rather than the viewer's session until the manifest beacons are
+ * plumbed through to the provider.
+ */
+const createQuortexProvider = (config = {}) => {
+    const { adApiBase, tenantName } = config;
+    if (!adApiBase) {
+        // Loud, but not thrown: this runs inside the host's render effect via
+        // `startSsaiMonitoring`, and taking the app down over a config typo is worse
+        // than an overlay that never appears and says why.
+        log.error({ adApiBase, tenantName }, 'quortex provider requires `adApiBase`');
+    }
+    return {
+        id: 'quortex',
+        resolve: async (adId, signal) => {
+            if (!adApiBase) {
+                throw new Error('quortex provider is missing `adApiBase`');
+            }
+            const raw = await fetchCreativeJson('quortex', buildQuortexUrl(adApiBase, tenantName, adId), signal);
+            return mapApiResponse({ ...raw, creativeId: raw.creativeId || adId });
+        },
+        fireImpression: fireDefaultImpression,
+    };
+};
+// --- VAST provider ---------------------------------------------------------
+const mapVastResponse = async (creativeId, signal) => {
+    const vastClient$1 = new vastClient.VASTClient();
+    const parsedVAST = await vastClient$1.get(creativeId, { timeout: 8000 });
+    if (signal.aborted) {
+        throw new DOMException('aborted', 'AbortError');
+    }
+    const validAd = parsedVAST.ads.find((ad) => ad.creatives.length > 0);
+    if (!validAd) {
+        throw new Error('no_valid_ad');
+    }
+    const advertiserValue = Array.isArray(validAd.advertiser)
+        ? validAd.advertiser.find((entry) => !!entry?.value)?.value
+        : undefined;
+    const advertiser = resolveAdvertiser(advertiserValue, validAd.title || undefined);
+    let iconUrl;
+    let clickThroughUrl;
+    let companion;
+    for (const creative of validAd.creatives) {
+        if (creative.type === 'linear') {
+            const linear = creative;
+            iconUrl = iconUrl || linear.icons?.find((icon) => !!icon?.staticResource)?.staticResource || undefined;
+            clickThroughUrl = clickThroughUrl || linear.videoClickThroughURLTemplate?.url;
+        }
+        if (creative.type === 'companion') {
+            const variation = creative.variations?.[0];
+            const staticResource = variation?.staticResources?.[0]?.url;
+            if (staticResource && !companion) {
+                companion = {
+                    staticResource,
+                    width: Number(variation?.width) || 0,
+                    height: Number(variation?.height) || 0,
+                    clickThrough: variation?.companionClickThroughURLTemplate?.url,
+                    clickTracking: (variation?.companionClickTrackingURLTemplates ?? [])
+                        .map((entry) => entry?.url)
+                        .filter((url) => !!url),
+                };
+            }
+        }
+    }
+    return {
+        creativeId,
+        advertiser,
+        title: validAd.title || advertiser,
+        iconUrl,
+        clickThroughUrl,
+        trackingEvents: [],
+        companion,
+    };
+};
+/**
+ * Maps a VAST tag into the normalized SsaiCreative shape.
+ *
+ * Note: `fireImpression` is intentionally left to the shared default for now.
+ * Proper VAST impression/tracking wiring through `VASTTracker` is a documented
+ * follow-up; it requires retaining the parsed ad/tracker per creative.
+ */
+const createVastProvider = (_config = {}) => {
+    return {
+        id: 'vast',
+        resolve: mapVastResponse,
+    };
+};
+/** Built-in provider factories keyed by name. */
+const BUILTIN_PROVIDERS = {
+    streamlayer: (config) => createStreamLayerProvider(config),
+    quortex: (config) => createQuortexProvider(config),
+    vast: () => createVastProvider(),
+};
+const isProviderInstance = (option) => {
+    return typeof option === 'object' && typeof option.resolve === 'function';
+};
+/**
+ * Resolve a {@link SsaiProviderOption} into a concrete {@link SsaiCreativeProvider}.
+ * Defaults to the StreamLayer provider (using `fallbackConfig`) when no option is
+ * supplied.
+ */
+const resolveProvider = (option, fallbackConfig) => {
+    if (!option) {
+        return createStreamLayerProvider(fallbackConfig);
+    }
+    if (typeof option === 'string') {
+        return BUILTIN_PROVIDERS[option](fallbackConfig);
+    }
+    if (isProviderInstance(option)) {
+        return option;
+    }
+    return BUILTIN_PROVIDERS[option.name](option.config ?? fallbackConfig);
+};
+
+exports.BUILTIN_PROVIDERS = BUILTIN_PROVIDERS;
+exports.DEFAULT_CREATIVE_API_BASE = DEFAULT_CREATIVE_API_BASE;
+exports.createQuortexProvider = createQuortexProvider;
+exports.createStreamLayerProvider = createStreamLayerProvider;
+exports.createVastProvider = createVastProvider;
+exports.fireBeacon = fireBeacon;
+exports.fireDefaultImpression = fireDefaultImpression;
+exports.fireTrackingEvents = fireTrackingEvents;
+exports.resolveProvider = resolveProvider;

package/lib/cjs/units/vast-tracker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One place that constructs a `VASTTracker`.
+ *
+ * Every StreamLayer surface that reports VAST beacons — the GAM video player, both pause-ad
+ * renderers and the Standard Ad sidebar — needs the same `(ad, creative, variation)` triple, and
+ * each was assembling it by hand behind its own `@ts-ignore`. The parsed shapes those triples
+ * come from (`AdData` / `AdCompanion` / `AdNonLinear`) are defined in this package, so the
+ * mapping belongs here too.
+ *
+ * Deliberately *only* construction: when a beacon may fire, and how a surface de-duplicates its
+ * impression, stays with that surface. Those policies differ on purpose (per-ad-id in module
+ * scope for the sidebar, per component instance for the pause ads, per tracker identity for the
+ * player) and they are billing-visible, so collapsing them here would silently change counts.
+ */
+import { VASTTracker, VastAd, VastCompanionAd, VastCreativeCompanion, VastCreativeLinear, VastCreativeNonLinear, VastNonLinearAd } from '@dailymotion/vast-client';
+import type { AdCompanion, AdData } from './external-ad.js';
+/** The creative (and, for non-linear creatives, the variation) a tracker reports through. */
+export type VastTrackerTarget = {
+    ad: VastAd;
+    /** `<Linear>`, `<NonLinearAds>` or `<CompanionAds>` — whichever owns the `<TrackingEvents>`. */
+    creative: VastCreativeLinear | VastCreativeNonLinear | VastCreativeCompanion;
+    /**
+     * The `<NonLinear>` / `<Companion>` variation. Omitted for a linear creative; required for the
+     * others, since the variation is what owns their `creativeView`, click-through and click
+     * trackers.
+     */
+    variation?: VastNonLinearAd | VastCompanionAd;
+};
+export declare const createVastTracker: ({ ad, creative, variation }: VastTrackerTarget) => VASTTracker;
+/**
+ * A tracker for a single `<Companion>`. A `<CompanionAds>` creative has no creative-level
+ * `<TrackingEvents>` — each variation owns its own `creativeView` — so a companion is reported
+ * through its own tracker. `undefined` when the companion was parsed without them (nothing to
+ * report against).
+ */
+export declare const createCompanionTracker: (ad: VastAd, companion: AdCompanion) => VASTTracker | undefined;
+/**
+ * The creative a parsed ad reports its impression / playback beacons through, in the order the
+ * shells draw them: the `<Linear>` creative first, then the `<NonLinear>` still, then — for a tag
+ * whose only creative is `<CompanionAds>` — the companion that was actually drawn.
+ *
+ * `drawnCompanion` is a parameter rather than `adData.companion` because only the rendering shell
+ * knows which companion reached the screen, and reporting one that did not is a false view.
+ */
+export declare const resolveVastTrackerTarget: (adData: AdData, drawnCompanion?: AdCompanion) => VastTrackerTarget | undefined;

package/lib/cjs/units/vast-tracker.js

@@ -0,0 +1,64 @@
+'use strict';
+
+var vastClient = require('@dailymotion/vast-client');
+
+/**
+ * One place that constructs a `VASTTracker`.
+ *
+ * Every StreamLayer surface that reports VAST beacons — the GAM video player, both pause-ad
+ * renderers and the Standard Ad sidebar — needs the same `(ad, creative, variation)` triple, and
+ * each was assembling it by hand behind its own `@ts-ignore`. The parsed shapes those triples
+ * come from (`AdData` / `AdCompanion` / `AdNonLinear`) are defined in this package, so the
+ * mapping belongs here too.
+ *
+ * Deliberately *only* construction: when a beacon may fire, and how a surface de-duplicates its
+ * impression, stays with that surface. Those policies differ on purpose (per-ad-id in module
+ * scope for the sidebar, per component instance for the pause ads, per tracker identity for the
+ * player) and they are billing-visible, so collapsing them here would silently change counts.
+ */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
+const createVastTracker = ({ ad, creative, variation }) => 
+// The first argument is the `VASTClient` the tracker may update; every surface here drives
+// playback itself and only wants the beacons, so it is always `null`.
+//
+// The type shim declares the 3rd argument as `VastCreativeLinear` and the 4th as another
+// *creative*. At runtime `vast-client` accepts any creative in the 3rd and expects the
+// `<Companion>` / `<NonLinear>` *variation* in the 4th. The casts encode that runtime contract
+// once here rather than at every call site.
+new vastClient.VASTTracker(null, ad, creative, variation);
+/**
+ * A tracker for a single `<Companion>`. A `<CompanionAds>` creative has no creative-level
+ * `<TrackingEvents>` — each variation owns its own `creativeView` — so a companion is reported
+ * through its own tracker. `undefined` when the companion was parsed without them (nothing to
+ * report against).
+ */
+const createCompanionTracker = (ad, companion) => companion.creative && companion.variation
+    ? createVastTracker({ ad, creative: companion.creative, variation: companion.variation })
+    : undefined;
+/**
+ * The creative a parsed ad reports its impression / playback beacons through, in the order the
+ * shells draw them: the `<Linear>` creative first, then the `<NonLinear>` still, then — for a tag
+ * whose only creative is `<CompanionAds>` — the companion that was actually drawn.
+ *
+ * `drawnCompanion` is a parameter rather than `adData.companion` because only the rendering shell
+ * knows which companion reached the screen, and reporting one that did not is a false view.
+ */
+const resolveVastTrackerTarget = (adData, drawnCompanion) => {
+    // `AdData.creative` is not optional in the type but `getCreative` can return nothing: a
+    // programmatic tag does not have to carry a `<Linear>` creative.
+    if (adData.creative) {
+        return { ad: adData.ad, creative: adData.creative };
+    }
+    if (adData.nonLinear) {
+        return { ad: adData.ad, creative: adData.nonLinear.creative, variation: adData.nonLinear.variation };
+    }
+    if (drawnCompanion?.creative && drawnCompanion.variation) {
+        return { ad: adData.ad, creative: drawnCompanion.creative, variation: drawnCompanion.variation };
+    }
+    return undefined;
+};
+
+exports.createCompanionTracker = createCompanionTracker;
+exports.createVastTracker = createVastTracker;
+exports.resolveVastTrackerTarget = resolveVastTrackerTarget;