@streamlayer/feature-advertisement 1.2.0 → 1.2.1-rc.12.pc6c8e1c0

package/classic/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../lib/classic/cjs/index.js",
+  "module": "../lib/classic/index.js",
+  "types": "../lib/cjs/index.d.ts"
+}

package/lib/advertisement.d.ts

@@ -1,10 +1,10 @@
 import { AbstractFeatureUnit, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
-import { externalAd } from './units/external-ad';
-import { externalPauseAd, type ExternalPauseAdOptions } from './units/external-pause-ad';
-import { type PauseAdListOptions, type PauseAdStore } from './units/pause-ad';
-import { type SsaiProviderOption } from './units/ssai-providers';
-import { type HlsLike, type SsaiDebugSnapshot } from './units/ssai-detector';
-import { type SsaiAdBreakStore } from './units/ssai-ad-break';
+import { externalAd } from './units/external-ad.js';
+import { externalPauseAd, type ExternalPauseAdOptions } from './units/external-pause-ad.js';
+import { type PauseAdListOptions, type PauseAdStore } from './units/pause-ad.js';
+import { type SsaiProviderOption } from './units/ssai-providers.js';
+import { type HlsLike, type SsaiDebugSnapshot } from './units/ssai-detector.js';
+import { type SsaiAdBreakStore } from './units/ssai-ad-break.js';
 export type ExternalAdStore = ReturnType<ReturnType<typeof externalAd>>;
 export type ExternalPauseAdStore = ReturnType<ReturnType<typeof externalPauseAd>>;
 export type SsaiMonitorOptions = {

package/lib/advertisement.js

@@ -1,14 +1,14 @@
 import { AbstractFeatureUnit, createSingleStore, eventBus } from '@streamlayer/sdk-web-interfaces';
 import { createLogger } from '@streamlayer/sdk-web-logger';
-import { externalAd } from './units/external-ad';
-import { externalPauseAd } from './units/external-pause-ad';
-import { pauseAdListStore } from './units/pause-ad';
-import { SsaiCreativeCache } from './units/ssai-creative';
-import { resolveProvider } from './units/ssai-providers';
-import { createSsaiDetector, } from './units/ssai-detector';
-import { createSsaiAdBreakStore } from './units/ssai-ad-break';
-import { ssaiq } from './units/ssai-log';
-import { preloadCreativeAssets } from './units/ssai-preload';
+import { externalAd } from './units/external-ad.js';
+import { externalPauseAd } from './units/external-pause-ad.js';
+import { pauseAdListStore } from './units/pause-ad.js';
+import { SsaiCreativeCache } from './units/ssai-creative.js';
+import { resolveProvider } from './units/ssai-providers.js';
+import { createSsaiDetector, } from './units/ssai-detector.js';
+import { createSsaiAdBreakStore } from './units/ssai-ad-break.js';
+import { ssaiq } from './units/ssai-log.js';
+import { preloadCreativeAssets } from './units/ssai-preload.js';
 export class Advertisement extends AbstractFeatureUnit {
     getExternalAd;
     getExternalPauseAd;

package/lib/cjs/advertisement.d.ts

@@ -0,0 +1,64 @@
+import { AbstractFeatureUnit, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import { externalAd } from './units/external-ad.js';
+import { externalPauseAd, type ExternalPauseAdOptions } from './units/external-pause-ad.js';
+import { type PauseAdListOptions, type PauseAdStore } from './units/pause-ad.js';
+import { type SsaiProviderOption } from './units/ssai-providers.js';
+import { type HlsLike, type SsaiDebugSnapshot } from './units/ssai-detector.js';
+import { type SsaiAdBreakStore } from './units/ssai-ad-break.js';
+export type ExternalAdStore = ReturnType<ReturnType<typeof externalAd>>;
+export type ExternalPauseAdStore = ReturnType<ReturnType<typeof externalPauseAd>>;
+export type SsaiMonitorOptions = {
+    player?: HlsLike;
+    videoRef?: HTMLVideoElement;
+    manifestUrl?: string;
+    /** Creative provider: a ready instance, a built-in name, or `{ name, config }`. Defaults to `streamlayer`. */
+    provider?: SsaiProviderOption;
+};
+export declare class Advertisement extends AbstractFeatureUnit {
+    getExternalAd: (adUrl?: string) => [ExternalAdStore, string];
+    getExternalPauseAd: (adUrl: string, options: ExternalPauseAdOptions) => [ExternalPauseAdStore, string];
+    getPauseAdList: (options: PauseAdListOptions) => PauseAdStore;
+    readonly ssaiAdBreak: SsaiAdBreakStore;
+    startSsaiMonitoring: (options: SsaiMonitorOptions) => void;
+    stopSsaiMonitoring: () => void;
+    /**
+     * Fire the impression tracking pixel for a creative. Called by the UI the
+     * moment the bar actually renders the creative, so "impression" means the
+     * viewer saw it (not merely that metadata resolved).
+     */
+    fireSsaiImpression: (creativeId: string) => void;
+    /**
+     * Fire a named tracking beacon for a creative (`clickThrough`, or any event
+     * the creative carries). Lifecycle beacons — `start`, the quartiles and
+     * `complete` — are fired automatically by the detector as playback crosses
+     * them; this is for the ones only the UI knows about.
+     */
+    fireSsaiTracking: (creativeId: string, event: string) => void;
+    /**
+     * Fire the companion's `clickTracking` beacons. Exposed for hosts that render
+     * the companion banner themselves — the TV overlay has no companion surface,
+     * so nothing in this SDK calls it.
+     */
+    fireSsaiCompanionClick: (creativeId: string) => void;
+    /**
+     * User-dismissed the current break: hide the bar now and keep it hidden for
+     * the rest of this break (a later break/creative shows again).
+     */
+    dismissSsaiBreak: () => void;
+    /**
+     * Read-only timing introspection of the running SSAI monitor (null while no
+     * monitor runs). Feeds the demo app's SSAI debug window; safe to poll.
+     */
+    getSsaiDebugSnapshot: () => SsaiDebugSnapshot | null;
+    private externalAdStores;
+    private externalPauseAdStores;
+    private externalPauseAdEnabled;
+    private pauseAdStore;
+    private pauseAdEnabled;
+    private ssaiDetector;
+    private ssaiCache;
+    private log;
+    constructor(instance: StreamLayerContext);
+    connect: () => void;
+    disconnect: () => void;
+}

package/lib/cjs/advertisement.js

@@ -0,0 +1,322 @@
+'use strict';
+
+var sdkWebInterfaces = require('@streamlayer/sdk-web-interfaces');
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+var externalAd = require('./units/external-ad.js');
+var externalPauseAd = require('./units/external-pause-ad.js');
+var pauseAd = require('./units/pause-ad.js');
+var ssaiCreative = require('./units/ssai-creative.js');
+var ssaiProviders = require('./units/ssai-providers.js');
+var ssaiDetector = require('./units/ssai-detector.js');
+var ssaiAdBreak = require('./units/ssai-ad-break.js');
+var ssaiLog = require('./units/ssai-log.js');
+var ssaiPreload = require('./units/ssai-preload.js');
+
+class Advertisement extends sdkWebInterfaces.AbstractFeatureUnit {
+    getExternalAd;
+    getExternalPauseAd;
+    getPauseAdList;
+    ssaiAdBreak = ssaiAdBreak.createSsaiAdBreakStore();
+    startSsaiMonitoring;
+    stopSsaiMonitoring;
+    /**
+     * Fire the impression tracking pixel for a creative. Called by the UI the
+     * moment the bar actually renders the creative, so "impression" means the
+     * viewer saw it (not merely that metadata resolved).
+     */
+    fireSsaiImpression;
+    /**
+     * Fire a named tracking beacon for a creative (`clickThrough`, or any event
+     * the creative carries). Lifecycle beacons — `start`, the quartiles and
+     * `complete` — are fired automatically by the detector as playback crosses
+     * them; this is for the ones only the UI knows about.
+     */
+    fireSsaiTracking;
+    /**
+     * Fire the companion's `clickTracking` beacons. Exposed for hosts that render
+     * the companion banner themselves — the TV overlay has no companion surface,
+     * so nothing in this SDK calls it.
+     */
+    fireSsaiCompanionClick;
+    /**
+     * User-dismissed the current break: hide the bar now and keep it hidden for
+     * the rest of this break (a later break/creative shows again).
+     */
+    dismissSsaiBreak;
+    /**
+     * Read-only timing introspection of the running SSAI monitor (null while no
+     * monitor runs). Feeds the demo app's SSAI debug window; safe to poll.
+     */
+    getSsaiDebugSnapshot;
+    externalAdStores = new Map();
+    externalPauseAdStores = new Map();
+    externalPauseAdEnabled = new Map();
+    pauseAdStore = null;
+    pauseAdEnabled = null;
+    ssaiDetector = null;
+    ssaiCache = null;
+    log;
+    constructor(instance) {
+        super();
+        this.log = sdkWebLogger.createLogger('advertisement');
+        const externalAdGenerator = externalAd.externalAd(instance);
+        const externalPauseAdGenerator = externalPauseAd.externalPauseAd(instance);
+        const pauseAdGenerator = pauseAd.pauseAdListStore(instance);
+        this.fireSsaiImpression = () => undefined;
+        this.fireSsaiTracking = () => undefined;
+        this.fireSsaiCompanionClick = () => undefined;
+        this.dismissSsaiBreak = () => undefined;
+        // Stable across start/stop cycles — always answers from the CURRENT detector.
+        this.getSsaiDebugSnapshot = () => this.ssaiDetector?.getDebugSnapshot() ?? null;
+        this.getPauseAdList = (options) => {
+            if (this.pauseAdStore) {
+                const $enabled = this.pauseAdEnabled;
+                const wasDisabled = $enabled.get() === false;
+                $enabled.set(options.$enabled);
+                if (wasDisabled && options.$enabled) {
+                    window.requestAnimationFrame(() => {
+                        if (this.pauseAdStore)
+                            this.pauseAdStore.$list.revalidate();
+                    });
+                }
+                return this.pauseAdStore;
+            }
+            const $enabled = sdkWebInterfaces.createSingleStore(options.$enabled);
+            this.pauseAdEnabled = $enabled;
+            this.pauseAdStore = pauseAdGenerator($enabled, options);
+            return this.pauseAdStore;
+        };
+        this.getExternalAd = (adUrl = '') => {
+            if (this.externalAdStores.has(adUrl)) {
+                const $store = this.externalAdStores.get(adUrl);
+                return [$store, adUrl];
+            }
+            const store = externalAdGenerator(adUrl);
+            this.externalAdStores.set(adUrl, store);
+            return [store, adUrl];
+        };
+        this.getExternalPauseAd = (adUrl, options) => {
+            // Store identity is (template, url): the template selects a DIFFERENT creative
+            // from the SAME tag, so the two must not share a store. Required because the
+            // cache-hit branch below applies only `$enabled` and drops the rest of `options`.
+            const storeKey = `${options.template ?? 'default'}::${adUrl}`;
+            if (this.externalPauseAdStores.has(storeKey)) {
+                const $enabled = this.externalPauseAdEnabled.get(storeKey);
+                const $store = this.externalPauseAdStores.get(storeKey);
+                const shouldRevalidate = $enabled.get() === false && options.$enabled === true;
+                $enabled.set(options.$enabled);
+                if (shouldRevalidate) {
+                    window.requestAnimationFrame(() => {
+                        $store.revalidate();
+                    });
+                }
+                // The 2nd element MUST stay the BARE url — `ExposedPauseAd` compares it to
+                // `vastUrlRef.current` (index.tsx:121) to scope store errors to the selected tag.
+                return [$store, adUrl];
+            }
+            const $enabled = sdkWebInterfaces.createSingleStore(options.$enabled);
+            const store = externalPauseAdGenerator(adUrl, $enabled, options);
+            this.externalPauseAdEnabled.set(storeKey, $enabled);
+            this.externalPauseAdStores.set(storeKey, store);
+            return [store, adUrl];
+        };
+        this.startSsaiMonitoring = (options) => {
+            this.stopSsaiMonitoring();
+            const provider = ssaiProviders.resolveProvider(options.provider);
+            const cache = new ssaiCreative.SsaiCreativeCache(provider);
+            this.ssaiCache = cache;
+            /**
+             * Every beacon the SDK fires gets a line, with the URL it was fired at.
+             * The narrative log is read as a live trace of one ad, and "we called the
+             * ad server's own tracking URL" is as much of the story as the request
+             * that fetched the creative in the first place.
+             */
+            const logBeacon = (creativeId, event) => {
+                const url = cache.peek(creativeId)?.trackingEvents?.find((entry) => entry.event === event)?.url;
+                ssaiLog.ssaiq.info({ creativeId, event, url }, `[beacon] ${event} fired — ${creativeId}`);
+            };
+            this.fireSsaiImpression = (creativeId) => {
+                // The UI only calls this once the bar is actually rendered, so this is
+                // the moment the viewer saw the ad — not the moment it resolved.
+                ssaiLog.ssaiq.info({ creativeId }, `[ad] ad on screen — ${cache.peek(creativeId)?.advertiser || creativeId}`);
+                logBeacon(creativeId, 'impression');
+                cache.fireImpressionById(creativeId);
+            };
+            this.fireSsaiTracking = (creativeId, event) => {
+                logBeacon(creativeId, event);
+                cache.fireTrackingById(creativeId, event);
+            };
+            this.fireSsaiCompanionClick = (creativeId) => {
+                cache.fireCompanionClickById(creativeId);
+            };
+            // Creative ids whose artwork preload has completed. Tracked apart from the
+            // cache: `peek` alone would let the bar show with a logo still in flight.
+            const preloadedIds = new Set();
+            /**
+             * Resolve + warm a creative the moment its id shows up in the manifest —
+             * typically seconds before its break starts, since the playhead trails the
+             * live edge. By break start the sync fast-path in `loadCreative` then flips
+             * the store straight to 'ready'. Failure here is only a debug note: the
+             * break may still be minutes away, and `loadCreative` retries (and warns)
+             * when the ad actually starts.
+             */
+            const prefetchCreative = (creativeId) => {
+                cache
+                    .resolve(creativeId)
+                    .then((creative) => ssaiPreload.preloadCreativeAssets(creative).then(() => creative))
+                    .then((creative) => {
+                    preloadedIds.add(creativeId);
+                    ssaiLog.ssaiq.info({ creativeId }, `[ad] creative ready — ${creative.advertiser} (artwork preloaded)`);
+                })
+                    .catch(() => {
+                    // Already on `ssaiq` from the provider; the break may still be
+                    // minutes away, and `loadCreative` retries when it actually starts.
+                });
+            };
+            const publishReady = (range, creative) => {
+                this.ssaiAdBreak.set({
+                    creativeId: range.creativeId,
+                    creative,
+                    status: 'ready',
+                    startMs: range.startMs,
+                    durationSec: range.durationSec,
+                });
+                // "loaded" = metadata resolved. Impression (eventBus + pixel) fires
+                // from the UI when the bar is actually rendered, not here.
+                sdkWebInterfaces.eventBus.emit('ssaiAdBreak', {
+                    action: 'vastLoaded',
+                    payload: {
+                        creativeId: creative.creativeId,
+                        advertiser: creative.advertiser,
+                        clickThroughUrl: creative.clickThroughUrl,
+                    },
+                });
+            };
+            const loadCreative = (range) => {
+                // Fast path: prefetched at discovery, artwork warm — go straight to
+                // 'ready'. Skipping the 'detecting' hop matters for pods in particular:
+                // it momentarily empties the store, which the UI renders as the bar
+                // starting to close between two back-to-back ads.
+                const prefetched = cache.peek(range.creativeId);
+                if (prefetched && preloadedIds.has(range.creativeId)) {
+                    publishReady(range, prefetched);
+                    return;
+                }
+                this.ssaiAdBreak.set({
+                    creativeId: range.creativeId,
+                    status: 'detecting',
+                    startMs: range.startMs,
+                    durationSec: range.durationSec,
+                });
+                cache
+                    .resolve(range.creativeId)
+                    // Warm the artwork BEFORE flipping to 'ready', so the bar fades in with
+                    // its logo already decoded instead of popping it in mid-animation. Capped
+                    // internally, so a slow image host delays nothing.
+                    .then((creative) => ssaiPreload.preloadCreativeAssets(creative).then(() => {
+                    preloadedIds.add(range.creativeId);
+                    return creative;
+                }))
+                    .then((creative) => {
+                    const current = this.ssaiAdBreak.get();
+                    // Re-checked after the preload as well as the fetch: the break can end
+                    // while either is in flight.
+                    if (!current || current.creativeId !== range.creativeId) {
+                        return;
+                    }
+                    publishReady(range, creative);
+                })
+                    .catch((error) => {
+                    this.log.warn(error, 'ssai creative resolution failed');
+                });
+            };
+            this.ssaiDetector = ssaiDetector.createSsaiDetector({
+                player: options.player,
+                videoRef: options.videoRef,
+                manifestUrl: options.manifestUrl,
+                onAdDiscovered: (creativeId) => {
+                    prefetchCreative(creativeId);
+                },
+                onBreakStart: (range) => {
+                    sdkWebInterfaces.eventBus.emit('ssaiAdBreak', {
+                        action: 'breakStart',
+                        payload: { creativeId: range.creativeId },
+                    });
+                    loadCreative(range);
+                },
+                onCreativeChange: (range) => {
+                    loadCreative(range);
+                },
+                onAdEnding: (range) => {
+                    const current = this.ssaiAdBreak.get();
+                    // Only a bar currently showing this creative has anything to wind
+                    // down — a dismissed or still-resolving break stays as it is.
+                    if (!current || current.creativeId !== range.creativeId || current.status !== 'ready') {
+                        return;
+                    }
+                    this.ssaiAdBreak.set({ ...current, status: 'ending' });
+                },
+                onProgress: (range, event) => {
+                    // Logged by the detector as `progress:<event>` at the moment playback
+                    // crosses the marker; nothing to add here.
+                    cache.fireTrackingById(range.creativeId, event);
+                },
+                onBreakEnd: () => {
+                    const current = this.ssaiAdBreak.get();
+                    sdkWebInterfaces.eventBus.emit('ssaiAdBreak', {
+                        action: 'breakEnd',
+                        payload: { creativeId: current?.creativeId },
+                    });
+                    this.ssaiAdBreak.set(null);
+                },
+            });
+            this.dismissSsaiBreak = () => {
+                this.ssaiDetector?.dismissActiveBreak();
+                this.ssaiAdBreak.set(null);
+            };
+        };
+        this.stopSsaiMonitoring = () => {
+            if (this.ssaiDetector) {
+                this.ssaiDetector.destroy();
+                this.ssaiDetector = null;
+            }
+            if (this.ssaiCache) {
+                this.ssaiCache.destroy();
+                this.ssaiCache = null;
+            }
+            this.fireSsaiImpression = () => undefined;
+            this.fireSsaiTracking = () => undefined;
+            this.fireSsaiCompanionClick = () => undefined;
+            this.dismissSsaiBreak = () => undefined;
+            this.ssaiAdBreak.set(null);
+        };
+    }
+    connect = () => {
+        this.log.debug('connect');
+    };
+    disconnect = () => {
+        this.log.debug('disconnect');
+        this.stopSsaiMonitoring();
+        this.externalAdStores.forEach((store) => {
+            store.off();
+        });
+        this.externalAdStores.clear();
+        this.externalPauseAdStores.forEach((store) => {
+            store.off();
+        });
+        this.externalPauseAdEnabled.forEach((enabled) => {
+            enabled.off();
+        });
+        this.externalPauseAdEnabled.clear();
+        this.externalPauseAdStores.clear();
+        if (this.pauseAdStore) {
+            this.pauseAdStore.$list.off();
+            this.pauseAdStore.$index.off();
+            this.pauseAdEnabled?.off();
+            this.pauseAdStore = null;
+            this.pauseAdEnabled = null;
+        }
+    };
+}
+
+exports.Advertisement = Advertisement;

package/lib/cjs/index.d.ts

@@ -0,0 +1,21 @@
+/// <reference path="../vast-client.d.ts" />
+import { StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+declare module '@streamlayer/sdk-web-interfaces' {
+    interface StreamLayerSDK {
+        advertisement: import('./advertisement.js').Advertisement;
+    }
+}
+export { type ExternalAdStore, type ExternalPauseAdStore, type SsaiMonitorOptions } from './advertisement.js';
+export { type GAMStaticCore, type PauseAdTemplate, isFullbleedVideoTemplate } from './units/external-pause-ad.js';
+export { INSIGHT_BODY_MAX_LENGTH, type PauseAdCard, type PauseAdKind, type PauseAdMediaMode, } from './units/pause-ad-card.js';
+export { type PauseAdStore } from './units/pause-ad.js';
+export { type AdStore, type AdData, type AdCompanion, type AdNonLinear } from './units/external-ad.js';
+export { selectSponsorLogo, type SponsorLogoAsset } from './units/sponsor-logo.js';
+export { gam, type GamNonceResult, type PalNonceManager } from './units/gam.js';
+export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, type VastTrackerTarget, } from './units/vast-tracker.js';
+export { type SsaiCreative, type SsaiTrackingEvent, type SsaiCompanion, type SsaiProgressEvent, DEFAULT_CREATIVE_API_BASE, } from './units/ssai-creative.js';
+export { type SsaiCreativeProvider, type SsaiProviderOption, type SsaiProviderName, type SsaiProviderConfig, type StreamLayerProviderConfig, type QuortexProviderConfig, createStreamLayerProvider, createQuortexProvider, createVastProvider, resolveProvider, fireBeacon, fireTrackingEvents, BUILTIN_PROVIDERS, } from './units/ssai-providers.js';
+export { type SsaiDateRange, type SsaiTrackingMarker, type HlsLike, type SsaiClockSource, type SsaiDebugEvent, type SsaiDebugRange, type SsaiDebugSnapshot, } from './units/ssai-detector.js';
+export { preloadImages, preloadCreativeAssets, DEFAULT_PRELOAD_TIMEOUT_MS } from './units/ssai-preload.js';
+export { type SsaiAdBreakState, type SsaiAdBreakStatus, type SsaiAdBreakStore } from './units/ssai-ad-break.js';
+export declare const advertisement: (instance: StreamLayerContext, _opts: unknown, done: () => void) => void;

package/lib/cjs/index.js

@@ -0,0 +1,41 @@
+'use strict';
+
+var advertisement$1 = require('./advertisement.js');
+var externalPauseAd = require('./units/external-pause-ad.js');
+var pauseAdCard = require('./units/pause-ad-card.js');
+var sponsorLogo = require('./units/sponsor-logo.js');
+var gam = require('./units/gam.js');
+var vastTracker = require('./units/vast-tracker.js');
+var ssaiProviders = require('./units/ssai-providers.js');
+var ssaiPreload = require('./units/ssai-preload.js');
+
+const advertisement = (instance, _opts, done) => {
+    instance.sdk.advertisement = new advertisement$1.Advertisement(instance);
+    instance.sdk.onMount({ name: 'advertisement' }, () => {
+        instance.sdk.advertisement.connect();
+        return () => {
+            instance.sdk.advertisement.disconnect();
+        };
+    });
+    done();
+};
+
+exports.isFullbleedVideoTemplate = externalPauseAd.isFullbleedVideoTemplate;
+exports.INSIGHT_BODY_MAX_LENGTH = pauseAdCard.INSIGHT_BODY_MAX_LENGTH;
+exports.selectSponsorLogo = sponsorLogo.selectSponsorLogo;
+exports.gam = gam.gam;
+exports.createCompanionTracker = vastTracker.createCompanionTracker;
+exports.createVastTracker = vastTracker.createVastTracker;
+exports.resolveVastTrackerTarget = vastTracker.resolveVastTrackerTarget;
+exports.BUILTIN_PROVIDERS = ssaiProviders.BUILTIN_PROVIDERS;
+exports.DEFAULT_CREATIVE_API_BASE = ssaiProviders.DEFAULT_CREATIVE_API_BASE;
+exports.createQuortexProvider = ssaiProviders.createQuortexProvider;
+exports.createStreamLayerProvider = ssaiProviders.createStreamLayerProvider;
+exports.createVastProvider = ssaiProviders.createVastProvider;
+exports.fireBeacon = ssaiProviders.fireBeacon;
+exports.fireTrackingEvents = ssaiProviders.fireTrackingEvents;
+exports.resolveProvider = ssaiProviders.resolveProvider;
+exports.DEFAULT_PRELOAD_TIMEOUT_MS = ssaiPreload.DEFAULT_PRELOAD_TIMEOUT_MS;
+exports.preloadCreativeAssets = ssaiPreload.preloadCreativeAssets;
+exports.preloadImages = ssaiPreload.preloadImages;
+exports.advertisement = advertisement;

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/cjs/units/ad-macros.d.ts

@@ -0,0 +1,7 @@
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
+/**
+ * Fill the macros this SDK knows in an ad-tag URL. One timestamp per call, so a tag naming the macro
+ * twice stays self-consistent. `params` is read as given — the caller passes the host's CURRENT
+ * values at request time.
+ */
+export declare const substituteAdTagMacros: (url: string, params?: AdTagParams) => string;

package/lib/cjs/units/ad-macros.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Ad-tag macro substitution, for every ad server — not just GAM.
+ *
+ * Studio stores a programmatic tag verbatim (`gamRawUrl`, returned untouched by
+ * `processGamAdvertisement`), so whatever macros the ad server's own tag builder emitted reach the
+ * SDK literal. `gam()` used to fill only the GAM `[placeholder]` token, and only for
+ * `pubads.g.doubleclick.net` — every other vendor's tag went out with its macros unexpanded.
+ *
+ * That is not inert. Measured against the ADITION tag on event 11089
+ * (`…/banner?…&ts=[timestamp]&clickurl=[clickmacro]`): ADITION prepends the value of `clickurl` to
+ * its own redi URL, so a literal `[clickmacro]` came back inside `<CompanionClickThrough>` as
+ * `[clickmacro]https%3A%2F%2Fad1…` — a broken click-through. Sending `clickurl=` empty answers with
+ * a valid redi URL.
+ *
+ * **Two sources.** The cache buster is the SDK's own. The consent family — `${GDPR}` and
+ * `${GDPR_CONSENT_<gvlid>}`, IAB TCF, where the id is the vendor's Global Vendor List entry (39 is
+ * ADITION / Virtual Minds) — and the click macro come from the host app (`AdTagParams`, set through
+ * the `adTagParams` option or `sdk.setAdTagParams`). The SDK never reads a CMP and never guesses
+ * consent: a value the host did not pass goes out EMPTY, which ad servers read as "unknown" — never
+ * as `gdpr=0`. Empty rather than literal because a literal is not inert either: ADITION copied
+ * `${GDPR}` into its own redirect URL (`gdpr%3D%24%7BGDPR%7D`). See
+ * `docs/wiki/programmatic-ads-macros.md`.
+ *
+ * An unknown macro is left exactly as configured, which is what keeps the GAM `[placeholder]`
+ * tokens for the PAL path (`gam.ts` fills those per parameter, not per token).
+ */
+/**
+ * All three spellings in the wild — `[NAME]` (IAB / SpotX), `${NAME}` (Google) and bare `{NAME}` —
+ * each with its delimiters either literal or PERCENT-ENCODED.
+ *
+ * Neither half of that is theoretical. ADITION emitted `[timestamp]` / `[clickmacro]` for the
+ * campaign on event 11089 and `{CACHEBUSTER}` / `{GDPR}` for the one on 6203 — same ad server, same
+ * advertiser, different tag builder. And Studio stores the 6203 tag as `ts=%7BCACHEBUSTER%7D`, so
+ * matching only literal braces made the whole substitution a silent no-op on it: an unexpanded
+ * macro raises no error and the ad server still answers 200. `searchParams.get()` decodes on read,
+ * which is what hides the encoding from anyone inspecting the parsed URL.
+ *
+ * The `$` is optional rather than a fourth branch — an unowned `${NAME}` still returns its full
+ * matched text, `$` included, so the brace forms cannot corrupt each other.
+ */
+const MACRO_PATTERN = /(?:\[|%5B)([a-z0-9_]+)(?:\]|%5D)|(?:\$|%24)?(?:\{|%7B)([a-z0-9_]+)(?:\}|%7D)/gi;
+/**
+ * Every host value lands inside a query-string VALUE, so it is encoded exactly once. That matters
+ * most for the click URL, which carries its own `?`/`&`: sent raw it re-opens the tag's query, the
+ * way the malformed 6203 tag did (`clickurl` truncated, every following parameter duplicated).
+ */
+const hostValue = (value) => (value ? encodeURIComponent(value) : '');
+const gdprConsent = ({ params }) => hostValue(params?.tcString);
+/**
+ * Macro name (lower-cased) → the value this SDK sends for it.
+ *
+ * `clickurl` / `clickmacro` take the host's click tracker, which the ad server PREPENDS to its own
+ * redirect — so the viewer's click passes host tracker → vendor redirect → landing page. The SDK
+ * does not fire that tracker itself; it would count the click twice. Without one it is empty, the
+ * documented "no player tracker" value. VAST click beacons are reported separately by
+ * `useSidebarVastTracker`.
+ */
+const MACRO_VALUES = {
+    // One family, one value: every name here means "make this request unique so nothing caches it".
+    // Epoch milliseconds satisfies that for all of them, and keeps the value already shipped for
+    // `timestamp` unchanged. (IAB defines `[CACHEBUSTING]` as a random 8-digit number and
+    // `[TIMESTAMP]` as ISO-8601, but those describe VAST *tracking* URLs; this substitution only
+    // ever touches the ad REQUEST url, where every ad server documents the parameter as a number.)
+    timestamp: ({ now }) => String(now),
+    cachebuster: ({ now }) => String(now),
+    cachebusting: ({ now }) => String(now),
+    clickmacro: ({ params }) => hostValue(params?.clickUrl),
+    clickurl: ({ params }) => hostValue(params?.clickUrl),
+    // `1` / `0` only from an explicit boolean — an absent value is unknown, not "does not apply".
+    gdpr: ({ params }) => (params?.gdprApplies === undefined ? '' : params.gdprApplies ? '1' : '0'),
+    gdpr_consent: gdprConsent,
+};
+/** `GDPR_CONSENT_<gvlid>`: the vendor id names whose tag this is; the value is the same TC string. */
+const GDPR_CONSENT_FOR_VENDOR = /^gdpr_consent_\d+$/;
+const resolveMacro = (name) => MACRO_VALUES[name] ?? (GDPR_CONSENT_FOR_VENDOR.test(name) ? gdprConsent : undefined);
+/**
+ * Fill the macros this SDK knows in an ad-tag URL. One timestamp per call, so a tag naming the macro
+ * twice stays self-consistent. `params` is read as given — the caller passes the host's CURRENT
+ * values at request time.
+ */
+const substituteAdTagMacros = (url, params) => {
+    const now = Date.now();
+    return url.replace(MACRO_PATTERN, (match, bracketed, braced) => {
+        const value = resolveMacro((bracketed ?? braced ?? '').toLowerCase());
+        return value ? value({ now, params }) : match;
+    });
+};
+
+exports.substituteAdTagMacros = substituteAdTagMacros;